mobile-debug-mcp 0.21.0 → 0.21.2

package/src/interact/android.ts

@@ -1,4 +1,4 @@
-import { WaitForElementResponse, TapResponse, SwipeResponse, TypeTextResponse, PressBackResponse } from "../types.js"
+import { TapResponse, SwipeResponse, TypeTextResponse, PressBackResponse } from "../types.js"
 import { execAdb, getAndroidDeviceMetadata, getDeviceInfo } from "../utils/android/utils.js"
 import { AndroidObserve } from "../observe/index.js"
 import { scrollToElementShared } from "../utils/ui/index.js"
@@ -7,37 +7,6 @@ import { scrollToElementShared } from "../utils/ui/index.js"
 export class AndroidInteract {
   private observe = new AndroidObserve();
 
-  async waitForElement(text: string, timeout: number, deviceId?: string): Promise<WaitForElementResponse> {
-    const metadata = await getAndroidDeviceMetadata("", deviceId)
-    const deviceInfo = getDeviceInfo(deviceId || 'default', metadata)
-    const startTime = Date.now();
-    
-    while (Date.now() - startTime < timeout) {
-      try {
-        const tree = await this.observe.getUITree(deviceId);
-        
-        if (tree.error) {
-          return { device: deviceInfo, found: false, error: tree.error };
-        }
-
-        const element = tree.elements.find(e => e.text === text);
-        if (element) {
-          return { device: deviceInfo, 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: deviceInfo, found: false };
-  }
-
   async tap(x: number, y: number, deviceId?: string): Promise<TapResponse> {
     const metadata = await getAndroidDeviceMetadata("", deviceId)
     const deviceInfo = getDeviceInfo(deviceId || 'default', metadata)

package/src/interact/index.ts

@@ -39,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)
@@ -224,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
@@ -261,7 +260,7 @@ export class ToolsInteract {
     return { success: false, reason: 'timeout', lastFingerprint, elapsedMs: Date.now() - start }
   }
 
-  static async observeUntilHandler({ 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 }) {
+  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)
@@ -283,7 +282,7 @@ export class ToolsInteract {
         baselineLastLine = logsArr.length ? logsArr[logsArr.length - 1] : null
       }
     } catch (err) {
-      try { console.warn('observeUntil: failed to get baseline data (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.
@@ -294,7 +293,7 @@ export class ToolsInteract {
 
     // Optional initial observation delay requested by caller
     if (typeof observationDelayMs === 'number' && observationDelayMs > 0) {
-      try { console.log(`observeUntil: delaying observation for ${observationDelayMs}ms`) } catch { }
+      try { console.log(`waitForUI: delaying observation for ${observationDelayMs}ms`) } catch { }
       await sleep(observationDelayMs)
     }
 
@@ -311,40 +310,29 @@ export class ToolsInteract {
         // Evaluate condition per type
         if (type === 'ui') {
           try {
-                // Lightweight UI check: fetch UI tree and perform a normalized substring match to reduce overhead
-            try {
-              // Bound the UI tree fetch to avoid long blocking calls; prefer quick failure over hanging a poll
-              const withTimeout = (p: Promise<any>, ms: number) => Promise.race([p, new Promise(resolve => setTimeout(()=>resolve(null), ms))])
-              const tree = await withTimeout(ToolsObserve.getUITreeHandler({ platform, deviceId }), Math.min(pollInterval, 500)) as any
-              const elems = Array.isArray(tree && tree.elements) ? tree.elements : []
-              const qnorm = q.toLowerCase()
-              let matched: any = null
-              for (const el of elems) {
-                try {
-                  const txt = ((el && (el.text || el.label || el.value || el.contentDescription || el.accessibilityLabel)) || '')
-                  if (!txt) continue
-                  if (String(txt).toLowerCase().includes(qnorm)) { matched = el; break }
-                } catch { continue }
-              }
-              const isPresent = !!matched
-              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-tree-' + (match === 'present' ? 'present' : 'absent')
-                  const element = isPresent ? matched : 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 }
+              // 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
                 }
-              } else {
-                matchedAt = null
-                stableDuration = 0
-                lastObservedState = false
-              }
-            } catch (err) { console.error('observeUntil(ui) tree error:', err) }
-          } catch (err) { console.error('observeUntil(ui) find error:', err) }
+              } catch (err) { console.error('waitForUI(ui) find error:', err) }
+            } catch (err) { console.error('waitForUI(ui) outer error:', err) }
         } else if (type === 'log') {
           try {
             // Logs: presence semantics only (match 'present'). Stability not applicable (immediate)
@@ -372,7 +360,7 @@ export class ToolsInteract {
                 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
@@ -394,7 +382,7 @@ export class ToolsInteract {
                 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
@@ -413,7 +401,7 @@ export class ToolsInteract {
                 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) }
         }
 
       // Respect poll interval and avoid tight loop
@@ -424,7 +412,11 @@ export class ToolsInteract {
     let snapshot: any = null
     if (includeSnapshotOnFailure) {
       try {
-        snapshot = await ToolsObserve.captureDebugSnapshotHandler({ reason: `observe_until timeout for ${type}`, includeLogs: true, platform, deviceId })
+        // 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) }
       }

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/observe/android.ts

@@ -6,6 +6,7 @@ import { createWriteStream } from "fs"
 import { promises as fsPromises } from "fs"
 import path from "path"
 import { computeScreenFingerprint } from "../utils/ui/index.js"
+import { parsePngSize } from "../utils/image.js"
 
 const activeLogStreams: Map<string, { proc: any, file: string }> = new Map()
 
@@ -142,7 +143,7 @@ export class AndroidObserve {
         reject(new Error(`ADB screencap timed out after 10s`))
       }, 10000)
 
-      child.on('close', (code) => {
+      child.on('close', async (code) => {
         clearTimeout(timeout)
         if (code !== 0) {
           reject(new Error(stderr.trim() || `Screencap failed with code ${code}`))
@@ -152,28 +153,91 @@ export class AndroidObserve {
         const screenshotBuffer = Buffer.concat(chunks)
         const screenshotBase64 = screenshotBuffer.toString('base64')
 
-        execAdb(['shell', 'wm', 'size'], deviceId)
-          .then(sizeStdout => {
-            let width = 0
-            let height = 0
-            const match = sizeStdout.match(/Physical size: (\d+)x(\d+)/)
-            if (match) {
-              width = parseInt(match[1], 10)
-              height = parseInt(match[2], 10)
+        const parsed = parsePngSize(screenshotBuffer)
+        if (parsed.width > 0 && parsed.height > 0) {
+          // Attempt to convert to WebP (preferred) and provide JPEG fallback (awaited to avoid race)
+          try {
+            const sharpModule = await import('sharp'); const sharp = sharpModule && (sharpModule as any).default ? (sharpModule as any).default : sharpModule;
+            const buf = screenshotBuffer;
+            const img = sharp(buf);
+            const meta = await img.metadata().catch((err: any) => { console.error('sharp.metadata failed (Android):', err); return {} as any });
+            const hasAlpha = !!meta.hasAlpha || (meta.channels && meta.channels > 3);
+
+            let webpBuf: Buffer | null = null;
+            let jpegBuf: Buffer | null = null;
+            try {
+              webpBuf = await img.webp({ quality: 80 }).toBuffer();
+            } catch (err) {
+              console.error('WebP conversion failed (Android):', err instanceof Error ? err.message : String(err));
+              webpBuf = null;
             }
-            resolve({
-              device: deviceInfo,
-              screenshot: screenshotBase64,
-              resolution: { width, height }
+            try {
+              jpegBuf = await img.jpeg({ quality: 80 }).toBuffer();
+            } catch (err) {
+              console.error('JPEG conversion failed (Android):', err instanceof Error ? err.message : String(err));
+              jpegBuf = null;
+            }
+
+            if (hasAlpha) {
+              if (webpBuf) {
+                const webpB64 = webpBuf.toString('base64')
+                const jpegB64 = jpegBuf ? jpegBuf.toString('base64') : null
+                resolve({ device: deviceInfo, screenshot: webpB64, screenshot_mime: 'image/webp', screenshot_fallback: jpegB64, screenshot_fallback_mime: jpegB64 ? 'image/jpeg' : undefined, resolution: { width: parsed.width, height: parsed.height } } as any)
+                return
+              }
+              const pngB64 = buf.toString('base64')
+              resolve({ device: deviceInfo, screenshot: pngB64, screenshot_mime: 'image/png', resolution: { width: parsed.width, height: parsed.height } })
+              return
+            }
+
+            if (webpBuf) {
+              const webpB64 = webpBuf.toString('base64')
+              const jpegB64 = jpegBuf ? jpegBuf.toString('base64') : null
+              resolve({ device: deviceInfo, screenshot: webpB64, screenshot_mime: 'image/webp', screenshot_fallback: jpegB64, screenshot_fallback_mime: jpegB64 ? 'image/jpeg' : undefined, resolution: { width: parsed.width, height: parsed.height } } as any)
+              return
+            }
+
+            if (jpegBuf) {
+              resolve({ device: deviceInfo, screenshot: jpegBuf.toString('base64'), screenshot_mime: 'image/jpeg', resolution: { width: parsed.width, height: parsed.height } })
+              return
+            }
+
+            // No conversions succeeded; return original PNG
+            resolve({ device: deviceInfo, screenshot: screenshotBase64, screenshot_mime: 'image/png', resolution: { width: parsed.width, height: parsed.height } })
+            return
+          } catch (err) {
+            console.error('Screenshot conversion pipeline failed (Android):', err instanceof Error ? err.message : String(err));
+            // Conversion failed - fall back to original PNG with parsed resolution
+            resolve({ device: deviceInfo, screenshot: screenshotBase64, screenshot_mime: 'image/png', resolution: { width: parsed.width, height: parsed.height } })
+            return
+          }
+        } else {
+          // Fallback to querying wm size if parsing failed
+          execAdb(['shell', 'wm', 'size'], deviceId)
+            .then(sizeStdout => {
+              let width = 0
+              let height = 0
+              const match = sizeStdout.match(/Physical size: (\d+)x(\d+)/)
+              if (match) {
+                width = parseInt(match[1], 10)
+                height = parseInt(match[2], 10)
+              }
+              resolve({
+                device: deviceInfo,
+                screenshot: screenshotBase64,
+                screenshot_mime: 'image/png',
+                resolution: { width, height }
+              })
             })
-          })
-          .catch(() => {
-             resolve({
-              device: deviceInfo,
-              screenshot: screenshotBase64,
-              resolution: { width: 0, height: 0 }
+            .catch(() => {
+               resolve({
+                device: deviceInfo,
+                screenshot: screenshotBase64,
+                screenshot_mime: 'image/png',
+                resolution: { width: 0, height: 0 }
+              })
             })
-          })
+        }
       })
 
       child.on('error', (err) => {

package/src/observe/ios.ts

@@ -6,6 +6,7 @@ import { createWriteStream, promises as fsPromises } from 'fs'
 import path from 'path'
 import { parseLogLine } from '../utils/android/utils.js'
 import { computeScreenFingerprint } from '../utils/ui/index.js'
+import { parsePngSize } from '../utils/image.js'
 
 const delay = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));
 
@@ -146,13 +147,63 @@ export class iOSObserve {
       
       const buffer = await fs.readFile(tmpFile)
       const base64 = buffer.toString('base64')
-      
-      await fs.rm(tmpFile).catch(() => {})
 
+      const dims = parsePngSize(buffer)
+
+      // Try to generate WebP (preferred) and JPEG fallback using sharp (in-process, cross-platform)
+      try {
+        const sharpModule = await import('sharp'); const sharp = sharpModule && (sharpModule as any).default ? (sharpModule as any).default : sharpModule;
+        const img = sharp(buffer);
+        const meta = await img.metadata().catch((err: any) => { console.error('sharp.metadata failed:', err); return {} as any });
+
+        // If image has alpha channel, prefer lossless PNG to preserve transparency
+        const hasAlpha = !!meta.hasAlpha || (meta.channels && meta.channels > 3);
+
+        // Generate WebP and JPEG buffers; log failures
+        let webpBuf: Buffer | null = null;
+        let jpegBuf: Buffer | null = null;
+        try {
+          webpBuf = await img.webp({ quality: 80 }).toBuffer();
+        } catch (err) {
+          console.error('WebP conversion failed (iOS):', err instanceof Error ? err.message : String(err));
+          webpBuf = null;
+        }
+        try {
+          jpegBuf = await img.jpeg({ quality: 80 }).toBuffer();
+        } catch (err) {
+          console.error('JPEG conversion failed (iOS):', err instanceof Error ? err.message : String(err));
+          jpegBuf = null;
+        }
+
+        await fs.rm(tmpFile).catch(() => {});
+
+        if (hasAlpha) {
+          // preserve alpha: return PNG if WebP not available
+          if (webpBuf) {
+            return { device, screenshot: webpBuf.toString('base64'), screenshot_mime: 'image/webp', screenshot_fallback: base64, screenshot_fallback_mime: 'image/png', resolution: { width: dims.width, height: dims.height } }
+          }
+          // if webp unavailable, return original PNG
+          return { device, screenshot: base64, screenshot_mime: 'image/png', resolution: { width: dims.width, height: dims.height } }
+        }
+
+        // No alpha: prefer webp, fall back to jpeg
+        if (webpBuf) {
+          return { device, screenshot: webpBuf.toString('base64'), screenshot_mime: 'image/webp', screenshot_fallback: jpegBuf ? jpegBuf.toString('base64') : undefined, screenshot_fallback_mime: jpegBuf ? 'image/jpeg' : undefined, resolution: { width: dims.width, height: dims.height } }
+        }
+        if (jpegBuf) {
+          return { device, screenshot: jpegBuf.toString('base64'), screenshot_mime: 'image/jpeg', resolution: { width: dims.width, height: dims.height } }
+        }
+      } catch (err) {
+        console.error('Screenshot conversion pipeline failed (iOS):', err instanceof Error ? err.message : String(err));
+        // fall through to png fallback
+      }
+
+      await fs.rm(tmpFile).catch(() => {})
       return {
         device,
         screenshot: base64,
-        resolution: { width: 0, height: 0 },
+        screenshot_mime: 'image/png',
+        resolution: { width: dims.width, height: dims.height },
       }
     } catch (e) {
       await fs.rm(tmpFile).catch(() => {})

package/src/server.ts

@@ -340,8 +340,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
       }
     },
     {
-      name: "observe_until",
-      description: "Wait for a UI condition (element present/absent) and require a stability window before returning success. Network-based waiting is not required; UI-only synchronization is the default and primary mode.",
+      name: "wait_for_ui",
+      description: "Wait for a UI/log/screen/idle condition with a stability window before returning success.",
       inputSchema: {
         type: "object",
         properties: {
@@ -359,34 +359,6 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
 
 
-    {
-      name: "wait_for_element",
-      description: "Wait until a UI element with matching text appears on screen or timeout is reached.",
-      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"]
-      }
-    },
     {
       name: "find_element",
       description: "Find a UI element by semantic query (text, content-desc, resource-id, class). Returns best match.",
@@ -656,12 +628,17 @@ server.setRequestHandler(CallToolRequestSchema, async (request: SchemaOutput<typ
     if (name === "capture_screenshot") {
       const { platform, deviceId } = args as any
       const res = await ToolsObserve.captureScreenshotHandler({ platform, deviceId })
-      return {
-        content: [
-          { type: 'text', text: JSON.stringify({ device: res.device, result: { resolution: (res as any).resolution } }, null, 2) },
-          { type: 'image', data: (res as any).screenshot, mimeType: 'image/png' }
-        ]
-      }
+      const mime = (res as any).screenshot_mime || 'image/png'
+      const content: any[] = [
+        { type: 'text', text: JSON.stringify({ device: res.device, result: { resolution: (res as any).resolution, mimeType: mime } }, null, 2) },
+        { type: 'image', data: (res as any).screenshot, mimeType: mime }
+      ]
+      // If a jpeg fallback is available, include a small note and the fallback as an additional image block for compatibility
+      if ((res as any).screenshot_fallback) {
+        content.push({ type: 'text', text: JSON.stringify({ note: 'JPEG fallback included for compatibility', mimeType: (res as any).screenshot_fallback_mime || 'image/jpeg' }) })
+        content.push({ type: 'image', data: (res as any).screenshot_fallback, mimeType: (res as any).screenshot_fallback_mime || 'image/jpeg' })
+      }
+      return { content }
     }
 
     if (name === "capture_debug_snapshot") {
@@ -694,9 +671,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/types.ts

@@ -50,6 +50,9 @@ export interface GetCrashResponse {
 export interface CaptureAndroidScreenResponse {
   device: DeviceInfo;
   screenshot: string; // base64 encoded string
+  screenshot_mime?: string; // e.g. image/webp, image/jpeg, image/png
+  screenshot_fallback?: string; // optional fallback base64 (e.g., jpeg)
+  screenshot_fallback_mime?: string;
   resolution: {
     width: number;
     height: number;
@@ -59,6 +62,9 @@ export interface CaptureAndroidScreenResponse {
 export interface CaptureIOSScreenshotResponse {
   device: DeviceInfo;
   screenshot: string; // base64 encoded string
+  screenshot_mime?: string; // e.g. image/webp, image/jpeg, image/png
+  screenshot_fallback?: string; // optional fallback base64 (e.g., jpeg)
+  screenshot_fallback_mime?: string;
   resolution: {
     width: number;
     height: number;

package/src/utils/image.ts

@@ -0,0 +1,14 @@
+export function parsePngSize(buf: Buffer): { width: number; height: number } {
+  try {
+    if (!buf || buf.length < 24) return { width: 0, height: 0 };
+    // PNG signature + IHDR checks
+    if (buf.readUInt32BE(0) !== 0x89504e47 || buf.readUInt32BE(4) !== 0x0d0a1a0a) return { width: 0, height: 0 };
+    const ihdr = buf.toString('ascii', 12, 16);
+    if (ihdr !== 'IHDR') return { width: 0, height: 0 };
+    const width = buf.readUInt32BE(16);
+    const height = buf.readUInt32BE(20);
+    return { width, height };
+  } catch {
+    return { width: 0, height: 0 };
+  }
+}

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);