mobile-debug-mcp 0.20.1 → 0.21.1

package/src/interact/index.ts

@@ -29,7 +29,6 @@ interface UiElement {
   _interactable?: boolean
 }
 
-const STABLE_IDLE_MS = 1000
 
 export class ToolsInteract {
 
@@ -40,12 +39,6 @@ export class ToolsInteract {
     return { interact: interact as any, resolved, platform: effectivePlatform }
   }
 
-  static async waitForElementHandler({ platform, text, timeout, deviceId }: { platform: 'android' | 'ios', text: string, timeout?: number, deviceId?: string }) {
-    const effectiveTimeout = timeout ?? 10000
-    const { interact, resolved } = await ToolsInteract.getInteractionService(platform, deviceId)
-    return await interact.waitForElement(text, effectiveTimeout, resolved.id)
-  }
-
   static async tapHandler({ platform, x, y, deviceId }: { platform?: 'android' | 'ios', x: number, y: number, deviceId?: string }) {
     const { interact, resolved } = await ToolsInteract.getInteractionService(platform, deviceId)
     return await interact.tap(x, y, resolved.id)
@@ -225,6 +218,11 @@ export class ToolsInteract {
     return { found: true, element: outEl, score: scoreVal, confidence: scoreVal }
   }
 
+  static async waitForUIHandler({ type = 'ui', query, timeoutMs = 30000, pollIntervalMs = 300, includeSnapshotOnFailure = true, match = 'present', stability_ms = 700, observationDelayMs = 0, platform, deviceId }: { type?: 'ui' | 'log' | 'screen' | 'idle', query?: string, timeoutMs?: number, pollIntervalMs?: number, includeSnapshotOnFailure?: boolean, match?: 'present'|'absent', stability_ms?: number, observationDelayMs?: number, platform?: 'android' | 'ios', deviceId?: string }) {
+    // Backwards-compatible wrapper that delegates to the core waitForUICore implementation
+    return await ToolsInteract.waitForUICore({ type, query, timeoutMs, pollIntervalMs, includeSnapshotOnFailure, match, stability_ms, observationDelayMs, platform, deviceId })
+  }
+
   static async waitForScreenChangeHandler({ platform, previousFingerprint, timeoutMs = 5000, pollIntervalMs = 300, deviceId }: { platform?: 'android' | 'ios', previousFingerprint: string, timeoutMs?: number, pollIntervalMs?: number, deviceId?: string }) {
     const start = Date.now()
     let lastFingerprint: string | null = null
@@ -262,76 +260,94 @@ export class ToolsInteract {
     return { success: false, reason: 'timeout', lastFingerprint, elapsedMs: Date.now() - start }
   }
 
-  static async observeUntilHandler({ type, query, timeoutMs = 5000, pollIntervalMs = 200, platform, deviceId }: { type: 'ui' | 'log' | 'screen' | 'idle', query?: string, timeoutMs?: number, pollIntervalMs?: number, platform?: 'android' | 'ios', deviceId?: string }) {
+  static async waitForUICore({ type = 'ui', query, timeoutMs = 30000, pollIntervalMs = 300, includeSnapshotOnFailure = true, match = 'present', stability_ms = 700, observationDelayMs = 0, platform, deviceId }: { type?: 'ui' | 'log' | 'screen' | 'idle', query?: string, timeoutMs?: number, pollIntervalMs?: number, includeSnapshotOnFailure?: boolean, match?: 'present'|'absent', stability_ms?: number, observationDelayMs?: number, platform?: 'android' | 'ios', deviceId?: string }) {
     const start = Date.now()
     const deadline = start + (timeoutMs || 0)
     const q = (query === null || query === undefined) ? '' : String(query)
 
-    // Baseline state
-    let initialFingerprint: string | null = null
-    try {
-      const fpRes = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId }) as ScreenFingerprintResponse | null
-      initialFingerprint = fpRes?.fingerprint ?? null
-    } catch (err) { console.error('observeUntil: error getting initial fingerprint', err); initialFingerprint = null }
+    // Clamp polling interval to 250-500ms for consistent behavior
+    const pollInterval = Math.max(250, Math.min(pollIntervalMs || 300, 500))
 
-    // For logs, capture a baseline snapshot (count or last line) to avoid matching historical lines
+    // Baseline state (fetch in parallel but bound to short timeouts so observation starts promptly)
+    let initialFingerprint: string | null = null
     let baselineLastLine: string | null = null
     try {
-      const gl = await ToolsObserve.getLogsHandler({ platform, deviceId, lines: 200 })
-      const logsArr = Array.isArray((gl as any).logs) ? (gl as any).logs : []
-      baselineLastLine = logsArr.length ? logsArr[logsArr.length - 1] : null
+      const fpPromise = ToolsObserve.getScreenFingerprintHandler({ platform, deviceId }) as Promise<ScreenFingerprintResponse | null>
+      const logsPromise = ToolsObserve.getLogsHandler({ platform, deviceId, lines: 200 }) as Promise<any>
+      const withTimeout = (p: Promise<any>, ms: number) => Promise.race([p, new Promise(resolve => setTimeout(() => resolve(null), ms))])
+      const [fpRes, gl] = await Promise.all([withTimeout(fpPromise, 300), withTimeout(logsPromise, 500)])
+      if (fpRes && typeof fpRes === 'object') initialFingerprint = (fpRes as ScreenFingerprintResponse).fingerprint ?? null
+      if (gl) {
+        const logsArr = Array.isArray((gl as any).logs) ? (gl as any).logs : []
+        baselineLastLine = logsArr.length ? logsArr[logsArr.length - 1] : null
+      }
     } catch (err) {
-      // non-fatal but surface warning to aid debugging
-      try { console.warn('observeUntil: failed to get baseline logs (non-fatal):', err instanceof Error ? err.message : String(err)) } catch { }
+      try { console.warn('waitForUI: failed to get baseline data (non-fatal):', err instanceof Error ? err.message : String(err)) } catch { }
     }
 
-    
+    // Network-based waiting removed. Rely on UI and screen fingerprints for determinism.
     let lastChangeAt = Date.now()
     let prevFingerprint = initialFingerprint
 
     const sleep = (ms: number) => new Promise(r => setTimeout(r, ms))
 
+    // Optional initial observation delay requested by caller
+    if (typeof observationDelayMs === 'number' && observationDelayMs > 0) {
+      try { console.log(`waitForUI: delaying observation for ${observationDelayMs}ms`) } catch { }
+      await sleep(observationDelayMs)
+    }
+
     // Telemetry
     let pollCount = 0
-    let timeToMatch: number | null = null
+    let matchedAt: number | null = null
+    let lastObservedState: boolean | null = null
+    let stableDuration = 0
     let matchSource: string | null = null
 
     while (Date.now() <= deadline) {
       pollCount++
-      try {
+        const now = Date.now()
+        // Evaluate condition per type
         if (type === 'ui') {
-          // fast findElement with short timeout to avoid blocking
           try {
-            const found = await ToolsInteract.findElementHandler({ query: q, exact: false, timeoutMs: Math.min(500, timeoutMs || 500), platform, deviceId })
-            if (found && (found as any).found) {
-              timeToMatch = Date.now() - start
-              // determine matchSource heuristics
-              const el = (found as any).element || {}
-              if (el && el.resourceId && String(el.resourceId).toLowerCase().includes(q.toLowerCase())) matchSource = 'ui-resourceId'
-              else if (el && el.text && String(el.text).toLowerCase() === q.toLowerCase()) matchSource = 'ui-exact'
-              else matchSource = 'ui-partial'
-
-              return { success: true, type: 'ui', matched: true, details: `UI element matched '${q}'`, timestamp: Date.now(), element: (found as any).element, telemetry: { pollCount, timeToMatch, elapsedMs: Date.now() - start, matchSource } }
-            }
-          } catch (err) { console.error('observeUntil(ui) find error:', err) }
+              // Prefer using the public findElementHandler which tests can override. This avoids relying
+              // on resolveObserve/getUITree for unit tests which may not have devices available.
+              try {
+                const findRes = await (ToolsInteract as any).findElementHandler({ query: q, exact: false, timeoutMs: Math.min(500, pollInterval), platform, deviceId })
+                const isPresent = !!(findRes && (findRes as any).found)
+                const conditionTrue = (match === 'present') ? isPresent : !isPresent
+                if (conditionTrue) {
+                  if (matchedAt === null) matchedAt = Date.now()
+                  stableDuration = Date.now() - (matchedAt as number)
+                  lastObservedState = true
+                  if (stableDuration >= stability_ms) {
+                    matchSource = 'ui-find'
+                    const element = isPresent ? (findRes as any).element : null
+                    const now2 = Date.now()
+                    return { success: true, condition: match, query: q, poll_count: pollCount, duration_ms: now2 - start, stable_duration_ms: stableDuration, matchedElement: element, matchSource, timestamp: now2, type: 'ui', observed_state: lastObservedState ?? null }
+                  }
+                } else {
+                  matchedAt = null
+                  stableDuration = 0
+                  lastObservedState = false
+                }
+              } catch (err) { console.error('waitForUI(ui) find error:', err) }
+            } catch (err) { console.error('waitForUI(ui) outer error:', err) }
         } else if (type === 'log') {
           try {
-            // Try reading from active stream first
+            // Logs: presence semantics only (match 'present'). Stability not applicable (immediate)
             const stream = await ToolsObserve.readLogStreamHandler({ platform, sessionId: 'default', limit: 200 }) as any
             const entries = (stream && Array.isArray(stream.entries)) ? stream.entries : []
             for (const ent of entries) {
               const msg = ent && (ent.message || ent.msg || ent) ? (ent.message || ent.msg || ent) : ''
               if (q && String(msg).includes(q)) {
-                timeToMatch = Date.now() - start
-                matchSource = 'log-stream'
-                return { success: true, type: 'log', matched: true, details: `Log matched '${q}'`, timestamp: Date.now(), log: { message: msg, raw: ent }, telemetry: { pollCount, timeToMatch, elapsedMs: Date.now() - start, matchSource } }
+                const now2 = Date.now()
+                return { success: true, condition: 'present', query: q, poll_count: pollCount, duration_ms: now2 - start, stable_duration_ms: 0, matchedLog: { message: msg, raw: ent }, matchSource: 'log-stream', timestamp: now2, type: 'log', observed_state: true }
               }
             }
 
-            // Fallback to snapshot logs
             const gl = await ToolsObserve.getLogsHandler({ platform, deviceId, lines: 200 }) as any
             const logsArr = Array.isArray(gl && gl.logs) ? gl.logs : []
-            // Only consider new lines after baselineLastLine when possible
             let startIndex = 0
             if (baselineLastLine) {
               const idx = logsArr.lastIndexOf(baselineLastLine)
@@ -340,35 +356,33 @@ export class ToolsInteract {
             for (let i = startIndex; i < logsArr.length; i++) {
               const line = logsArr[i]
               if (q && String(line).includes(q)) {
-                timeToMatch = Date.now() - start
-                matchSource = 'log-snapshot'
-                return { success: true, type: 'log', matched: true, details: `Log matched '${q}'`, timestamp: Date.now(), log: { message: line }, telemetry: { pollCount, timeToMatch, elapsedMs: Date.now() - start, matchSource } }
+                const now2 = Date.now()
+                return { success: true, condition: 'present', query: q, poll_count: pollCount, duration_ms: now2 - start, stable_duration_ms: 0, matchedLog: { message: line }, matchSource: 'log-snapshot', timestamp: now2, type: 'log', observed_state: true }
               }
             }
-          } catch (err) { console.error('observeUntil(log) error:', err) }
+          } catch (err) { console.error('waitForUI(log) error:', err) }
         } else if (type === 'screen') {
           try {
             const fpRes = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId }) as ScreenFingerprintResponse | null
             const fp = fpRes?.fingerprint ?? null
             if (fp !== null && fp !== undefined && fp !== initialFingerprint) {
-              if (q) {
-                // optionally validate query against new screen context
-                try {
-                  const found = await ToolsInteract.findElementHandler({ query: q, exact: false, timeoutMs: Math.min(500, timeoutMs || 500), platform, deviceId })
-                  if (found && (found as any).found) {
-                    timeToMatch = Date.now() - start
-                    matchSource = 'screen-validated-ui'
-                    return { success: true, type: 'screen', matched: true, details: `Screen changed and query matched on new screen`, timestamp: Date.now(), newFingerprint: fp, element: (found as any).element, telemetry: { pollCount, timeToMatch, elapsedMs: Date.now() - start, matchSource } }
-                  }
-                } catch (err) { console.error('observeUntil(screen) find error:', err) }
-                // If query provided but not matched yet, continue polling until timeout
+              // when screen changed, require stability_ms where fingerprint remains the same
+              if (matchedAt === null) matchedAt = now
+              const confirmFp = (await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId }) as ScreenFingerprintResponse | null)?.fingerprint ?? null
+              if (confirmFp === fp) {
+                stableDuration = Date.now() - (matchedAt as number)
+                lastObservedState = true
+                if (stableDuration >= stability_ms) {
+                  const now2 = Date.now()
+                  return { success: true, condition: 'present', query: q, poll_count: pollCount, duration_ms: now2 - start, stable_duration_ms: stableDuration, newFingerprint: fp, matchSource: 'screen-fingerprint', timestamp: now2, type: 'screen', observed_state: lastObservedState ?? null }
+                }
               } else {
-                timeToMatch = Date.now() - start
-                matchSource = 'screen-fingerprint'
-                return { success: true, type: 'screen', matched: true, details: 'Screen fingerprint changed', timestamp: Date.now(), newFingerprint: fp, telemetry: { pollCount, timeToMatch, elapsedMs: Date.now() - start, matchSource } }
+                matchedAt = null
+                stableDuration = 0
+                lastObservedState = false
               }
             }
-          } catch (err) { console.error('observeUntil(screen) error:', err) }
+          } catch (err) { console.error('waitForUI(screen) error:', err) }
         } else if (type === 'idle') {
           try {
             const fpRes = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId }) as ScreenFingerprintResponse | null
@@ -376,33 +390,39 @@ export class ToolsInteract {
             if (fp !== prevFingerprint) {
               prevFingerprint = fp
               lastChangeAt = Date.now()
+              matchedAt = null
+              stableDuration = 0
+              lastObservedState = false
             } else {
-              if (Date.now() - lastChangeAt >= STABLE_IDLE_MS) {
-                timeToMatch = Date.now() - start
-                matchSource = 'idle-stable'
-                return { success: true, type: 'idle', matched: true, details: `UI stable for ${STABLE_IDLE_MS}ms`, timestamp: Date.now(), fingerprint: fp, telemetry: { pollCount, timeToMatch, elapsedMs: Date.now() - start, matchSource } }
+              const idleMs = Date.now() - lastChangeAt
+              lastObservedState = true
+              if (idleMs >= stability_ms) {
+                const now2 = Date.now()
+                return { success: true, condition: 'present', query: q, poll_count: pollCount, duration_ms: now2 - start, stable_duration_ms: idleMs, matchSource: 'idle-stable', timestamp: now2, type: 'idle', observed_state: lastObservedState ?? null }
               }
             }
-          } catch (err) { console.error('observeUntil(idle) error:', err) }
+          } catch (err) { console.error('waitForUI(idle) error:', err) }
         }
-      } catch (err) {
-        console.error('observeUntil: unexpected error', err)
-      }
 
       // Respect poll interval and avoid tight loop
-      await sleep(pollIntervalMs || 200)
+      await sleep(pollInterval)
     }
 
-    // On timeout, capture a failure snapshot to aid debugging (best-effort)
+    // On timeout, optionally capture a failure snapshot to aid debugging (best-effort)
     let snapshot: any = null
-    try {
-      snapshot = await ToolsObserve.captureDebugSnapshotHandler({ reason: `observe_until timeout for ${type}`, includeLogs: true, platform, deviceId })
-    } catch (err) {
-      snapshot = { error: err instanceof Error ? err.message : String(err) }
+    if (includeSnapshotOnFailure) {
+      try {
+        // Use dynamic import to avoid circular-initialization issues where the ToolsObserve
+        // binding captured earlier may not reflect test-time overrides. Importing at call
+        // time ensures the latest exported ToolsObserve object is used.
+        const Obs = await import('../observe/index.js')
+        snapshot = await (Obs as any).ToolsObserve.captureDebugSnapshotHandler({ reason: `wait_for_ui timeout for ${type}`, includeLogs: true, platform, deviceId })
+      } catch (err) {
+        snapshot = { error: err instanceof Error ? err.message : String(err) }
+      }
     }
 
     const elapsed = Date.now() - start
-    return { success: false, error: 'Timeout waiting for condition', type, timeoutMs, telemetry: { pollCount, elapsedMs: elapsed, matchSource: null }, snapshot }
-  }
-
+    return { success: false, condition: match, query: q, poll_count: pollCount, duration_ms: elapsed, stable_duration_ms: stableDuration, error: 'Timeout waiting for condition', snapshot, observed_state: lastObservedState ?? null }
+  }  
 }

package/src/interact/ios.ts

@@ -1,5 +1,5 @@
 import { spawn } from "child_process"
-import { WaitForElementResponse, TapResponse, SwipeResponse } from "../types.js"
+import { TapResponse, SwipeResponse } from "../types.js"
 import { getIOSDeviceMetadata, getIdbCmd, isIDBInstalled } from "../utils/ios/utils.js"
 import { iOSObserve } from "../observe/index.js"
 import { scrollToElementShared } from "../utils/ui/index.js"
@@ -7,36 +7,6 @@ import { scrollToElementShared } from "../utils/ui/index.js"
 export class iOSInteract {
   private observe = new iOSObserve();
 
-  async waitForElement(text: string, timeout: number, deviceId: string = "booted"): Promise<WaitForElementResponse> {
-    const device = await getIOSDeviceMetadata(deviceId);
-    const startTime = Date.now();
-    
-    while (Date.now() - startTime < timeout) {
-      try {
-        const tree = await this.observe.getUITree(deviceId);
-        
-        if (tree.error) {
-          return { device, found: false, error: tree.error };
-        }
-
-        const element = tree.elements.find(e => e.text === text);
-        if (element) {
-          return { device, found: true, element };
-        }
-      } catch (e) {
-        // Ignore errors during polling and retry
-        console.error("Error polling UI tree:", e);
-      }
-
-      const elapsed = Date.now() - startTime;
-      const remaining = timeout - elapsed;
-      if (remaining <= 0) break;
-      
-      await new Promise(resolve => setTimeout(resolve, Math.min(500, remaining)));
-    }
-    return { device, found: false };
-  }
-
   async tap(x: number, y: number, deviceId: string = "booted"): Promise<TapResponse> {
     const device = await getIOSDeviceMetadata(deviceId)
     

package/src/server.ts

@@ -340,33 +340,25 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
       }
     },
     {
-      name: "wait_for_element",
-      description: "Wait until a UI element with matching text appears on screen or timeout is reached.",
+      name: "wait_for_ui",
+      description: "Wait for a UI/log/screen/idle condition with a stability window before returning success.",
       inputSchema: {
         type: "object",
         properties: {
-          platform: {
-            type: "string",
-            enum: ["android", "ios"],
-            description: "Platform to check"
-          },
-          text: {
-            type: "string",
-            description: "Text content of the element to wait for"
-          },
-          timeout: {
-            type: "number",
-            description: "Max wait time in ms (default 10000)",
-            default: 10000
-          },
-          deviceId: {
-            type: "string",
-            description: "Device Serial/UDID. Defaults to connected/booted device."
-          }
-        },
-        required: ["platform", "text"]
+          type: { type: "string", enum: ["ui","log","screen","idle"], description: "Condition type to observe", default: "ui" },
+          query: { type: "string", description: "Optional query string for ui/log/screen types" },
+          timeoutMs: { type: "number", description: "Timeout in ms to wait for condition (default 30000)", default: 30000 },
+          pollIntervalMs: { type: "number", description: "Polling interval in ms (default 300, clamped to 250-500)", default: 300 },
+          match: { type: "string", enum: ["present","absent"], description: "Match mode for UI checks: 'present' or 'absent' (default 'present')", default: "present" },
+          stability_ms: { type: "number", description: "Stability window in ms that the condition must hold before returning success (default 700)", default: 700 },
+          includeSnapshotOnFailure: { type: "boolean", description: "Whether to include a debug snapshot on timeout (default true)", default: true },
+          platform: { type: "string", enum: ["android","ios"], description: "Optional platform override" },
+          deviceId: { type: "string", description: "Optional device serial/udid" }
+        }
       }
     },
+
+
     {
       name: "find_element",
       description: "Find a UI element by semantic query (text, content-desc, resource-id, class). Returns best match.",
@@ -674,9 +666,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request: SchemaOutput<typ
       return wrapResponse(res)
     }
 
-    if (name === "wait_for_element") {
-      const { platform, text, timeout, deviceId } = (args || {}) as any
-      const res = await ToolsInteract.waitForElementHandler({ platform, text, timeout, deviceId })
+
+    if (name === "wait_for_ui") {
+      const { type = 'ui', query, timeoutMs = 30000, pollIntervalMs = 300, includeSnapshotOnFailure = true, match = 'present', stability_ms = 700, observationDelayMs = 0, platform, deviceId } = (args || {}) as any
+      const res = await ToolsInteract.waitForUIHandler({ type, query, timeoutMs, pollIntervalMs, includeSnapshotOnFailure, match, stability_ms, observationDelayMs, platform, deviceId })
       return wrapResponse(res)
     }
 

package/src/system/gradle.ts

@@ -17,7 +17,7 @@ function readPropertiesFile(p: string): Record<string,string> {
       out[k] = v
     }
     return out
-  } catch (e: unknown) {
+  } catch {
     return {}
   }
 }
@@ -30,7 +30,7 @@ function javaBinExists(p?: string): boolean {
     const alt = path.join(p, 'Contents', 'Home', 'bin', 'java')
     if (existsSync(alt)) return true
     return false
-  } catch (e: unknown) { return false }
+  } catch { return false }
 }
 
 export async function checkGradle(): Promise<{ gradleJavaHome?: string; gradleValid: boolean; filesChecked: string[]; issues: string[]; suggestedFixes?: string[] }> {
@@ -62,7 +62,7 @@ export async function checkGradle(): Promise<{ gradleJavaHome?: string; gradleVa
         suggestedFixes.push(`Edit ${userProps} to remove or correct org.gradle.java.home`)
       }
     }
-  } catch (e: unknown) { /* ignore */ }
+  } catch { }
 
   // 3) system gradle.properties
   const systemProps = '/etc/gradle/gradle.properties'
@@ -77,7 +77,7 @@ export async function checkGradle(): Promise<{ gradleJavaHome?: string; gradleVa
         suggestedFixes.push(`Edit ${systemProps} to remove or correct org.gradle.java.home`)
       }
     }
-  } catch (e: unknown) { /* ignore */ }
+  } catch { }
 
   // 4) GRADLE_HOME fallback
   if (!gradleJavaHome && process.env.GRADLE_HOME) {

package/src/utils/android/utils.ts

@@ -78,7 +78,7 @@ export async function prepareGradle(projectPath: string): Promise<{ execCmd: str
   let gradleCheck
   try {
     gradleCheck = await checkGradle()
-  } catch (e: unknown) {
+  } catch {
     gradleCheck = { gradleJavaHome: undefined, gradleValid: false, filesChecked: [], issues: [] }
   }
 
@@ -117,7 +117,7 @@ export async function prepareGradle(projectPath: string): Promise<{ execCmd: str
     } else {
       // Invalid gradle java home detected: avoid passing it to Gradle and remove from spawn env
       console.debug(`[prepareGradle] Invalid org.gradle.java.home detected (${gradleCheck.gradleJavaHome}); removing from spawn env to avoid Gradle error.`)
-      try { delete env.GRADLE_JAVA_HOME } catch (e: unknown) { }
+      try { delete env.GRADLE_JAVA_HOME } catch { }
     }
   }
 

package/src/utils/resolve-device.ts

@@ -32,6 +32,12 @@ export async function resolveTargetDevice(opts: ResolveOptions): Promise<DeviceI
   const { platform, appId, prefer, deviceId } = opts
   const devices = await listDevices(platform, appId)
 
+  // During unit tests (no adb/xcrun available), provide a lightweight mock device so
+  // the observe/interact unit tests can run without real devices.
+  if ((!devices || devices.length === 0) && (process.env.NODE_ENV === 'test' || process.env.MCP_TEST_MOCK_DEVICES === '1')) {
+    return { id: 'mock', platform: platform || 'android', osVersion: '12', model: 'Pixel', simulator: true } as DeviceInfo
+  }
+
   if (deviceId) {
     const found = devices.find(d => d.id === deviceId)
     if (!found) throw new Error(`Device '${deviceId}' not found for platform ${platform}`)

package/test/interact/device/run-real-test.ts

@@ -1,19 +1,3 @@
-import { spawn } from 'child_process';
-import path from 'path';
-import { fileURLToPath } from 'url';
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-const ADB_PATH = process.env.ADB_PATH || process.env.ADB || 'adb';
-const TEST_FILE = path.join(__dirname, 'wait_for_element_real.ts');
-
-const childEnv = { ...process.env, ADB_PATH };
-const runner = process.env.RUNNER || 'npx';
-const runnerArgs = ['tsx', TEST_FILE];
-
-const child = spawn(runner, runnerArgs, {
-  env: childEnv,
-  stdio: 'inherit'
-});
-child.on('exit', (code) => {
-  process.exit(code || 0);
-});
+// wait_for_element device runner removed
+console.log('wait_for_element device runner removed');
+process.exit(0);

package/test/interact/unit/{observe_until.test.ts → wait_for_ui.test.ts}

@@ -2,7 +2,7 @@ import { ToolsInteract } from '../../../src/interact/index.js'
 import * as Observe from '../../../src/observe/index.js'
 
 async function runTests() {
-  console.log('Starting observe_until unit tests...')
+  console.log('Starting wait_for_ui unit tests...')
 
   const origFind = (ToolsInteract as any).findElementHandler
   const origReadLog = (Observe as any).ToolsObserve.readLogStreamHandler
@@ -17,7 +17,7 @@ async function runTests() {
     ;(Observe as any).ToolsObserve.captureDebugSnapshotHandler = async ({ reason }: any) => ({ reason, fingerprint: 'snap-123', ui_tree: null, logs: [] })
     // make findElement always fail
     (ToolsInteract as any).findElementHandler = async () => ({ found: false })
-    const resTimeout = await ToolsInteract.observeUntilHandler({ type: 'ui', query: 'WillNeverExist', timeoutMs: 500, pollIntervalMs: 100, platform: 'android' })
+    const resTimeout = await ToolsInteract.waitForUIHandler({ type: 'ui', query: 'WillNeverExist', timeoutMs: 500, pollIntervalMs: 100, platform: 'android' })
     const okTimeout = resTimeout && !(resTimeout as any).success && (resTimeout as any).snapshot && (resTimeout as any).snapshot.fingerprint === 'snap-123' && (resTimeout as any).telemetry && (resTimeout as any).telemetry.pollCount > 0
     console.log('Timeout Snapshot Test:', okTimeout ? 'PASS' : 'FAIL', JSON.stringify((resTimeout as any).telemetry || {}, null, 2))
     ;(Observe as any).ToolsObserve.captureDebugSnapshotHandler = origCapture
@@ -31,7 +31,7 @@ async function runTests() {
       return { found: false }
     }
 
-    const resUi = await ToolsInteract.observeUntilHandler({ type: 'ui', query: 'Generate Session', timeoutMs: 3000, pollIntervalMs: 100, platform: 'android' })
+    const resUi = await ToolsInteract.waitForUIHandler({ type: 'ui', query: 'Generate Session', timeoutMs: 3000, pollIntervalMs: 100, platform: 'android' })
     const okUi = resUi && (resUi as any).success && (resUi as any).telemetry && (resUi as any).telemetry.pollCount > 0 && (resUi as any).telemetry.timeToMatch >= 0
     console.log('UI Test:', okUi ? 'PASS' : 'FAIL', JSON.stringify((resUi as any).telemetry || {}, null, 2))
 
@@ -44,21 +44,21 @@ async function runTests() {
       return { device: {}, logs: ['INFO start', 'ERROR Exception occurred', 'Server: Boom'] }
     }
 
-    const resLog = await ToolsInteract.observeUntilHandler({ type: 'log', query: 'Server', timeoutMs: 3000, pollIntervalMs: 100, platform: 'android' })
+    const resLog = await ToolsInteract.waitForUIHandler({ type: 'log', query: 'Server', timeoutMs: 3000, pollIntervalMs: 100, platform: 'android' })
     const okLog = resLog && (resLog as any).success && (resLog as any).telemetry && (resLog as any).telemetry.pollCount > 0 && (resLog as any).telemetry.matchSource === 'log-snapshot'
     console.log('Log Test:', okLog ? 'PASS' : 'FAIL', JSON.stringify((resLog as any).telemetry || {}, null, 2))
 
     // Screen condition: fingerprint changes after a few polls
     let seq = ['A', 'A', 'B']
     ;(Observe as any).ToolsObserve.getScreenFingerprintHandler = async () => ({ fingerprint: seq.length ? seq.shift() : null })
-    const resScreen = await ToolsInteract.observeUntilHandler({ type: 'screen', timeoutMs: 3000, pollIntervalMs: 100, platform: 'android' })
+    const resScreen = await ToolsInteract.waitForUIHandler({ type: 'screen', timeoutMs: 3000, pollIntervalMs: 100, platform: 'android' })
     const okScreen = resScreen && (resScreen as any).success && (resScreen as any).telemetry && (resScreen as any).telemetry.matchSource === 'screen-fingerprint'
     console.log('Screen Test:', okScreen ? 'PASS' : 'FAIL', JSON.stringify((resScreen as any).telemetry || {}, null, 2))
 
     // Idle condition: stable fingerprints observed
     let idleSeq = ['X', 'X', 'X']
     ;(Observe as any).ToolsObserve.getScreenFingerprintHandler = async () => ({ fingerprint: idleSeq.length ? idleSeq.shift() : 'X' })
-    const resIdle = await ToolsInteract.observeUntilHandler({ type: 'idle', timeoutMs: 3000, pollIntervalMs: 100, platform: 'android' })
+    const resIdle = await ToolsInteract.waitForUIHandler({ type: 'idle', timeoutMs: 3000, pollIntervalMs: 100, platform: 'android' })
     const okIdle = resIdle && (resIdle as any).success && (resIdle as any).telemetry && (resIdle as any).telemetry.matchSource === 'idle-stable'
     console.log('Idle Test:', okIdle ? 'PASS' : 'FAIL', JSON.stringify((resIdle as any).telemetry || {}, null, 2))
 

package/test/observe/device/wait_for_element_real.ts

@@ -1,80 +1,3 @@
-import { AndroidInteract } from "../../src/interact/index.js";
-import { AndroidObserve } from "../../src/observe/index.js";
-
-// Usage: npx tsx test/wait_for_element_real.ts <deviceId> <appId>
-const args = process.argv.slice(2);
-const DEVICE_ID = args[0] || process.env.DEVICE_ID;
-const APP_ID = args[1] || process.env.APP_ID;
-
-if (!DEVICE_ID || !APP_ID) {
-  console.error("Usage: npx tsx test/wait_for_element_real.ts <deviceId> <appId> or set DEVICE_ID and APP_ID env vars");
-  process.exit(1);
-}
-
-async function runRealTest() {
-  console.log(`Connecting to device ${DEVICE_ID}...`);
-  const interact = new AndroidInteract();
-  const observe = new AndroidObserve();
-  try {
-    console.log(`\nStarting app ${APP_ID}...`);
-    await interact.startApp(APP_ID, DEVICE_ID);
-    console.log("Waiting 3s for app to render...");
-    await new Promise(r => setTimeout(r, 3000));
-
-    console.log("\nFetching UI Tree to find a target text...");
-    const tree = await observe.getUITree(DEVICE_ID);
-    if (tree.error) {
-      console.error("Failed to get UI Tree:", tree.error);
-      return;
-    }
-
-    const targetElement = tree.elements.find(e => e.text && e.text.length > 0 && e.visible);
-    if (!targetElement || !targetElement.text) {
-      console.warn("No visible text elements found on screen to test with.");
-      console.log("Elements found:", tree.elements.length);
-      return;
-    }
-
-    const targetText = targetElement.text;
-    console.log(`Found target element: "${targetText}"`);
-
-    console.log(`\nTest 1: Waiting for existing element "${targetText}" (should succeed)...`);
-    const start1 = Date.now();
-    const result1 = await interact.waitForElement(targetText, 5000, DEVICE_ID);
-    const elapsed1 = Date.now() - start1;
-    console.log(`Result: ${result1.found ? "PASS" : "FAIL"}`);
-    console.log(`Found Element: ${result1.element?.text}`);
-    console.log(`Time taken: ${elapsed1}ms`);
-
-    const missingText = "THIS_TEXT_SHOULD_NOT_EXIST_XYZ_123";
-    console.log(`\nTest 2: Waiting for missing element "${missingText}" (should timeout)...`);
-    const start2 = Date.now();
-    const result2 = await interact.waitForElement(missingText, 2000, DEVICE_ID);
-    const elapsed2 = Date.now() - start2;
-    console.log(`Result: ${!result2.found ? "PASS" : "FAIL"}`);
-    console.log(`Found: ${result2.found}`);
-    console.log(`Time taken: ${elapsed2}ms (expected ~2000ms)`);
-
-    console.log(`\nTest 3: Found after polling`);
-    let calls = 0;
-    AndroidObserve.prototype.getUITree = async function() {
-      calls++;
-      if (calls < 3) {
-        return { device: { platform: "android", id: "mock", osVersion: "12", model: "Pixel", simulator: true }, screen: "", resolution: { width: 1080, height: 1920 }, elements: [] };
-      }
-      return { device: { platform: "android", id: "mock", osVersion: "12", model: "Pixel", simulator: true }, screen: "", resolution: { width: 1080, height: 1920 }, elements: [{ text: "Target", type: "Button", contentDescription: null, clickable: true, enabled: true, visible: true, bounds: [0,0,100,100], resourceId: null }] };
-    } as any;
-
-    const start3 = Date.now();
-    const result3 = await interact.waitForElement("Target", 2000, DEVICE_ID);
-    const elapsed3 = Date.now() - start3;
-    console.log(`Result: ${result3.found ? "PASS" : "FAIL"}`);
-    console.log(`Calls: ${calls} ${calls === 3 ? "PASS" : "FAIL"}`);
-    console.log(`Elapsed time (should be >= 1000ms): ${elapsed3} ${elapsed3 >= 1000 ? "PASS" : "FAIL"}`);
-
-  } catch {
-    console.error("Test failed with error:", error);
-  }
-}
-
-runRealTest();
+// wait_for_element device runner removed
+console.log('wait_for_element device test removed');
+process.exit(0);