mobile-debug-mcp 0.14.0 → 0.16.0

package/src/{ios/observe.ts → observe/ios.ts}

@@ -1,12 +1,11 @@
 import { spawn } from "child_process"
 import { promises as fs } from "fs"
 import { GetLogsResponse, CaptureIOSScreenshotResponse, GetUITreeResponse, UIElement, DeviceInfo } from "../types.js"
-import { execCommand, getIOSDeviceMetadata, validateBundleId, getIdbCmd, getXcrunCmd, isIDBInstalled } from "./utils.js"
+import { execCommand, getIOSDeviceMetadata, validateBundleId, getIdbCmd, getXcrunCmd, isIDBInstalled } from "../utils/ios/utils.js"
 import { createWriteStream, promises as fsPromises } from 'fs'
 import path from 'path'
-import { parseLogLine } from '../android/utils.js'
-
-// --- Helper Functions Specific to Observe ---
+import { parseLogLine } from '../utils/android/utils.js'
+import { computeScreenFingerprint } from '../utils/ui/index.js'
 
 const delay = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));
 
@@ -25,7 +24,6 @@ interface IDBElement {
 
 function parseIDBFrame(frame: any): [number, number, number, number] {
   if (!frame) return [0, 0, 0, 0];
-  // Handle string frames like "{{0, 0}, {402, 874}}"
   if (typeof frame === 'string') {
     const nums = frame.match(/-?\d+(?:\.\d+)?/g);
     if (!nums || nums.length < 4) return [0, 0, 0, 0];
@@ -53,29 +51,25 @@ function traverseIDBNode(node: IDBElement, elements: UIElement[], parentIndex: n
 
   let currentIndex = -1;
 
-  // Prefer standard keys, fallback to alternatives
   const type = node.AXElementType || node.type || "unknown";
   const label = node.AXLabel || node.label || null;
   const value = node.AXValue || null;
   const frame = node.AXFrame || node.frame;
   const traits = node.AXTraits || [];
   
-  const clickable = traits.includes("UIAccessibilityTraitButton") || type === "Button" || type === "Cell"; // Cells are often clickable
+  const clickable = traits.includes("UIAccessibilityTraitButton") || type === "Button" || type === "Cell";
   
-  // Filtering Logic:
-  // Keep if clickable OR has visible text/label OR has value
-  // Also keep 'Window' or 'Application' types as they define the root structure often, though usually depth 0
   const isUseful = clickable || (label && label.length > 0) || (value && value.length > 0) || type === "Application" || type === "Window";
 
   if (isUseful) {
     const bounds = parseIDBFrame(frame);
     const element: UIElement = {
       text: label,
-      contentDescription: value, 
+      contentDescription: value,
       type: type,
       resourceId: node.AXUniqueId || null,
       clickable: clickable,
-      enabled: true, // idb usually returns enabled elements
+      enabled: true,
       visible: true,
       bounds: bounds,
       center: getCenter(bounds),
@@ -90,8 +84,6 @@ function traverseIDBNode(node: IDBElement, elements: UIElement[], parentIndex: n
     currentIndex = elements.length - 1;
   }
   
-  // If current node was skipped, children inherit parentIndex and depth (flattening)
-  // If current node was added, children use currentIndex and depth + 1
   const nextParentIndex = currentIndex !== -1 ? currentIndex : parentIndex;
   const nextDepth = currentIndex !== -1 ? depth + 1 : depth;
 
@@ -113,12 +105,8 @@ function traverseIDBNode(node: IDBElement, elements: UIElement[], parentIndex: n
   return currentIndex;
 }
 
-
-
-// iOS live log stream support (moved from ios/utils to observe)
 const iosActiveLogStreams: Map<string, { proc: ReturnType<typeof import('child_process').spawn>, file: string }> = new Map()
 
-// Test helpers
 export function _setIOSActiveLogStream(sessionId: string, file: string) {
   iosActiveLogStreams.set(sessionId, { proc: {} as any, file })
 }
@@ -133,9 +121,6 @@ export class iOSObserve {
   }
 
   async getLogs(appId?: string, deviceId: string = "booted"): Promise<GetLogsResponse> {
-    // If appId is provided, use predicate filtering
-    // Note: execFile passes args directly, so we don't need shell escaping for the predicate string itself,
-    // but we do need to construct the predicate correctly for log show.
     const args = ['simctl', 'spawn', deviceId, 'log', 'show', '--style', 'syslog', '--last', '1m']
     if (appId) {
       validateBundleId(appId)
@@ -157,25 +142,19 @@ export class iOSObserve {
     const tmpFile = `/tmp/mcp-ios-screenshot-${Date.now()}.png`
 
     try {
-      // 1. Capture screenshot to temp file
       await execCommand(['simctl', 'io', deviceId, 'screenshot', tmpFile], deviceId)
       
-      // 2. Read file as base64
       const buffer = await fs.readFile(tmpFile)
       const base64 = buffer.toString('base64')
       
-      // 3. Clean up
       await fs.rm(tmpFile).catch(() => {})
 
       return {
         device,
         screenshot: base64,
-        // Default resolution since we can't easily parse it without extra libs
-        // Clients will read the real dimensions from the PNG header anyway
         resolution: { width: 0, height: 0 },
       }
     } catch (e) {
-      // Ensure cleanup happens even on error
       await fs.rm(tmpFile).catch(() => {})
       throw new Error(`Failed to capture screenshot: ${e instanceof Error ? e.message : String(e)}`)
     }
@@ -184,7 +163,6 @@ export class iOSObserve {
   async getUITree(deviceId: string = "booted"): Promise<GetUITreeResponse> {
     const device = await getIOSDeviceMetadata(deviceId);
     
-    // idb is required
     const idbExists = await isIDBInstalled();
     if (!idbExists) {
        return {
@@ -196,10 +174,8 @@ export class iOSObserve {
        };
     }
 
-    // Resolve UDID if needed
     const targetUdid = (device.id && device.id !== 'booted') ? device.id : undefined;
 
-    // Retry Logic
     let jsonContent: any = null;
     let attempts = 0;
     const maxAttempts = 3;
@@ -207,7 +183,6 @@ export class iOSObserve {
     while (attempts < maxAttempts) {
       attempts++;
       try {
-         // Stabilization delay
          await delay(300 + (attempts * 100));
 
          const args = ['ui', 'describe-all', '--json'];
@@ -255,7 +230,6 @@ export class iOSObserve {
 
     try {
         const elements: UIElement[] = [];
-        // idb describe-all returns either a root object or an array of root nodes
         if (Array.isArray(jsonContent)) {
           for (const node of jsonContent) {
             traverseIDBNode(node, elements);
@@ -264,7 +238,6 @@ export class iOSObserve {
           traverseIDBNode(jsonContent, elements);
         }
 
-        // Infer resolution from root element if possible (usually the Window/Application frame)
         let width = 0;
         let height = 0;
         if (elements.length > 0) {
@@ -290,7 +263,17 @@ export class iOSObserve {
     }
   }
 
-  // --- Log stream methods ---
+  async getScreenFingerprint(deviceId: string = 'booted'): Promise<{ fingerprint: string | null; activity?: string; error?: string }> {
+    try {
+      const tree = await this.getUITree(deviceId)
+      if (!tree || tree.error) return { fingerprint: null, error: tree && (tree as any).error }
+
+      return computeScreenFingerprint(tree, null, 'ios', 50)
+    } catch (e) {
+      return { fingerprint: null, error: e instanceof Error ? e.message : String(e) }
+    }
+  }
+
   async startLogStream(bundleId: string, deviceId: string = 'booted', sessionId: string = 'default') : Promise<{ success: boolean; stream_started?: boolean; error?: string }> {
     try {
       const predicate = `process == "${bundleId}" or subsystem contains "${bundleId}"`
@@ -303,7 +286,6 @@ export class iOSObserve {
       const args = ['simctl', 'spawn', deviceId, 'log', 'stream', '--style', 'syslog', '--predicate', predicate]
       const proc = spawn(getXcrunCmd(), args)
 
-      // Prepare output file
       const tmpDir = process.env.TMPDIR || '/tmp'
       const file = path.join(tmpDir, `mobile-debug-ios-log-${sessionId}.ndjson`)
       const stream = createWriteStream(file, { flags: 'a' })

package/src/server.ts

@@ -14,11 +14,11 @@ import {
   InstallAppResponse
 } from "./types.js"
 
-import { ToolsManage } from './tools/manage.js'
-import { ToolsInteract } from './tools/interact.js'
-import { ToolsObserve } from './tools/observe.js'
-import { AndroidManage } from './android/manage.js'
-import { iOSManage } from './ios/manage.js'
+import { ToolsManage } from './manage/index.js'
+import { ToolsInteract } from './interact/index.js'
+import { ToolsObserve } from './observe/index.js'
+import { AndroidManage } from './manage/index.js'
+import { iOSManage } from './manage/index.js'
 
 
 const server = new Server(
@@ -283,6 +283,32 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         }
       }
     },
+    {
+      name: "get_screen_fingerprint",
+      description: "Generate a stable fingerprint representing the current visible screen (activity + visible UI elements).",
+      inputSchema: {
+        type: "object",
+        properties: {
+          platform: { type: "string", enum: ["android", "ios"], description: "Optional platform override (android|ios)" },
+          deviceId: { type: "string", description: "Optional device id/udid to target" }
+        }
+      }
+    },
+    {
+      name: "wait_for_screen_change",
+      description: "Wait until the current screen fingerprint differs from a provided previousFingerprint. Useful to wait for navigation/animation completion.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          platform: { type: "string", enum: ["android", "ios"], description: "Optional platform override (android|ios)" },
+          previousFingerprint: { type: "string", description: "The fingerprint to compare against (required)" },
+          timeoutMs: { type: "number", description: "Timeout in ms to wait for change (default 5000)", default: 5000 },
+          pollIntervalMs: { type: "number", description: "Polling interval in ms (default 300)", default: 300 },
+          deviceId: { type: "string", description: "Optional device id/udid to target" }
+        },
+        required: ["previousFingerprint"]
+      }
+    },
     {
       name: "wait_for_element",
       description: "Wait until a UI element with matching text appears on screen or timeout is reached.",
@@ -311,6 +337,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         required: ["platform", "text"]
       }
     },
+
     {
       name: "tap",
       description: "Simulate a finger tap on the device screen at specific coordinates.",
@@ -579,6 +606,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       return wrapResponse(res)
     }
 
+    if (name === "get_screen_fingerprint") {
+      const { platform, deviceId } = (args || {}) as any
+      const res = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId })
+      return wrapResponse(res)
+    }
+
+    if (name === "wait_for_screen_change") {
+      const { platform, previousFingerprint, timeoutMs, pollIntervalMs, deviceId } = (args || {}) as any
+      const res = await ToolsInteract.waitForScreenChangeHandler({ platform, previousFingerprint, timeoutMs, pollIntervalMs, deviceId })
+      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 })
@@ -644,7 +683,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 const transport = new StdioServerTransport()
 
 async function main() {
-  await server.connect(transport)
+  await (server as any).connect(transport)
 }
 
 main().catch((error) => {

package/src/types.ts

@@ -143,3 +143,4 @@ export interface InstallAppResponse {
   error?: string;
   diagnostics?: any;
 }
+

package/src/{android → utils/android}/utils.ts

@@ -1,8 +1,8 @@
-import { spawn } from 'child_process'
-import { DeviceInfo, UIElement } from "../types.js"
+import { DeviceInfo, UIElement } from "../../types.js"
 import { promises as fsPromises, existsSync } from 'fs'
 import path from 'path'
-import { detectJavaHome } from '../utils/java.js'
+import { detectJavaHome } from '../java.js'
+import { execCmd } from '../exec.js'
 
 export function getAdbCmd() { return process.env.ADB_PATH || 'adb' }
 
@@ -83,87 +83,20 @@ import type { SpawnOptions } from 'child_process'
 
 export type SpawnOptionsWithTimeout = SpawnOptions & { timeout?: number }
 
-export function execAdb(args: string[], deviceId?: string, options: SpawnOptionsWithTimeout = {}): Promise<string> {
+export async function execAdb(args: string[], deviceId?: string, options: SpawnOptionsWithTimeout = {}): Promise<string> {
   const adbArgs = getAdbArgs(args, deviceId)
-  return new Promise((resolve, reject) => {
-    // Extract timeout from options if present, otherwise pass options to spawn
-    const { timeout: customTimeout, ...spawnOptions } = options;
-    
-    // Use spawn instead of execFile for better stream control and to avoid potential buffering hangs
-    const child = spawn(getAdbCmd(), adbArgs, spawnOptions)
-    
-    let stdout = ''
-    let stderr = ''
-
-    if (child.stdout) {
-      child.stdout.on('data', (data) => {
-        stdout += data.toString()
-      })
-    }
-
-    if (child.stderr) {
-      child.stderr.on('data', (data) => {
-        stderr += data.toString()
-      })
-    }
-
-    const timeoutMs = getAdbTimeout(args, customTimeout)
-
-
-    const timeout = setTimeout(() => {
-      child.kill()
-      reject(new Error(`ADB command timed out after ${timeoutMs}ms: ${args.join(' ')}`))
-    }, timeoutMs)
-
-    child.on('close', (code) => {
-      clearTimeout(timeout)
-      if (code !== 0) {
-        // If there's an actual error (non-zero exit code), reject
-        reject(new Error(stderr.trim() || `Command failed with code ${code}`))
-      } else {
-        // If exit code is 0, resolve with stdout
-        resolve(stdout.trim())
-      }
-    })
-
-    child.on('error', (err) => {
-      clearTimeout(timeout)
-      reject(err)
-    })
-  })
+  const timeoutMs = getAdbTimeout(args, options.timeout)
+  const res = await execCmd(getAdbCmd(), adbArgs, { timeout: timeoutMs, env: options.env as any, cwd: typeof options.cwd === 'string' ? options.cwd : undefined, shell: !!options.shell })
+  if (res.exitCode !== 0) throw new Error(res.stderr || `Command failed with code ${res.exitCode}`)
+  return res.stdout
 }
 
 // Spawn adb but return full streams and exit code so callers can implement fallbacks or stream output
-export function spawnAdb(args: string[], deviceId?: string, options: SpawnOptionsWithTimeout = {}): Promise<{ stdout: string, stderr: string, code: number | null }> {
+export async function spawnAdb(args: string[], deviceId?: string, options: SpawnOptionsWithTimeout = {}): Promise<{ stdout: string, stderr: string, code: number | null }> {
   const adbArgs = getAdbArgs(args, deviceId)
-  return new Promise((resolve, reject) => {
-    const { timeout: customTimeout, ...spawnOptions } = options
-    const child = spawn(getAdbCmd(), adbArgs, spawnOptions)
-
-    let stdout = ''
-    let stderr = ''
-
-    if (child.stdout) child.stdout.on('data', d => { stdout += d.toString() })
-    if (child.stderr) child.stderr.on('data', d => { stderr += d.toString() })
-
-    const timeoutMs = getAdbTimeout(args, customTimeout)
-
-
-    const timeout = setTimeout(() => {
-      try { child.kill() } catch {}
-      reject(new Error(`ADB command timed out after ${timeoutMs}ms: ${args.join(' ')}`))
-    }, timeoutMs)
-
-    child.on('close', (code) => {
-      clearTimeout(timeout)
-      resolve({ stdout: stdout.trim(), stderr: stderr.trim(), code })
-    })
-
-    child.on('error', (err) => {
-      clearTimeout(timeout)
-      reject(err)
-    })
-  })
+  const timeoutMs = getAdbTimeout(args, options.timeout)
+  const res = await execCmd(getAdbCmd(), adbArgs, { timeout: timeoutMs, env: options.env as any, cwd: typeof options.cwd === 'string' ? options.cwd : undefined, shell: !!options.shell })
+  return { stdout: res.stdout, stderr: res.stderr, code: res.exitCode }
 }
 
 export function getDeviceInfo(deviceId: string, metadata: Partial<DeviceInfo> = {}): DeviceInfo {

package/src/{cli → utils/cli}/ios/run-ios-smoke.ts

@@ -1,5 +1,5 @@
-import { iOSObserve } from '../../ios/observe.js';
-import { iOSManage } from '../../ios/manage.js';
+import { iOSObserve } from '../../../observe/index.js';
+import { iOSManage } from '../../../manage/index.js';
 
 async function main() {
   const appId = process.argv[2] || 'com.apple.springboard';

package/src/{cli → utils/cli}/ios/run-ios-ui-tree-tap.ts

@@ -1,5 +1,5 @@
-import { iOSObserve } from '../../ios/observe.js';
-import { iOSInteract } from '../../ios/interact.js';
+import { iOSObserve } from '../../../observe/index.js';
+import { iOSInteract } from '../../../interact/index.js';
 
 async function main() {
   const deviceId = 'booted';
@@ -18,7 +18,7 @@ async function main() {
     process.exit(3);
   }
 
-  const clickable = tree.elements.find(e => e.clickable) || tree.elements[0];
+  const clickable = tree.elements.find((e: any) => e.clickable) || tree.elements[0];
   console.log('Using element:', clickable.text || '(no text)', 'clickable=', clickable.clickable, 'center=', clickable.center);
   const [x,y] = clickable.center || [0,0];
 

package/src/utils/diagnostics.ts

@@ -37,7 +37,7 @@ export class DiagnosticError extends Error {
 
 // Exec ADB with diagnostics — moved from src/android/diagnostics.ts
 import { spawnSync } from 'child_process'
-import { getAdbCmd } from '../android/utils.js'
+import { getAdbCmd } from './android/utils.js'
 
 export function execAdbWithDiagnostics(args: string[], deviceId?: string) {
   const adbArgs = deviceId ? ['-s', deviceId, ...args] : args

package/src/utils/exec.ts

@@ -0,0 +1,33 @@
+import { spawn } from 'child_process'
+
+export type ExecOptions = { timeout?: number; env?: NodeJS.ProcessEnv; cwd?: string; shell?: boolean }
+
+export async function execCmd(cmd: string, args: string[], opts: ExecOptions = {}): Promise<{ exitCode: number | null, stdout: string, stderr: string }> {
+  const { timeout = 0, env, cwd, shell } = opts
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, { env: { ...process.env, ...(env || {}) }, cwd, shell })
+    let stdout = ''
+    let stderr = ''
+    if (child.stdout) child.stdout.on('data', (d) => { stdout += d.toString() })
+    if (child.stderr) child.stderr.on('data', (d) => { stderr += d.toString() })
+
+    let timedOut = false
+    const timer = timeout && timeout > 0 ? setTimeout(() => {
+      timedOut = true
+      try { child.kill() } catch { }
+      resolve({ exitCode: null, stdout: stdout.trim(), stderr: stderr.trim() })
+    }, timeout) : null
+
+    child.on('close', (code) => {
+      if (timer) clearTimeout(timer)
+      if (timedOut) return
+      resolve({ exitCode: code, stdout: stdout.trim(), stderr: stderr.trim() })
+    })
+
+    child.on('error', (err) => {
+      if (timer) clearTimeout(timer)
+      reject(err)
+    })
+  })
+}
+

package/src/{ios → utils/ios}/utils.ts

@@ -1,8 +1,8 @@
 import { execFile, spawn, execSync, spawnSync } from "child_process"
-import { DeviceInfo } from "../types.js"
+import { DeviceInfo } from "../../types.js"
 import { promises as fsPromises } from 'fs'
 import path from 'path'
-import { makeEnvSnapshot } from '../utils/diagnostics.js'
+import { makeEnvSnapshot } from '../diagnostics.js'
 
 export function getXcrunCmd() { return process.env.XCRUN_PATH || 'xcrun' }
 

package/src/utils/resolve-device.ts

@@ -1,6 +1,6 @@
 import { DeviceInfo } from "../types.js"
-import { listAndroidDevices } from "../android/utils.js"
-import { listIOSDevices } from "../ios/utils.js"
+import { listAndroidDevices } from "./android/utils.js"
+import { listIOSDevices } from "./ios/utils.js"
 
 export interface ResolveOptions {
   platform: "android" | "ios"

package/src/{tools/scroll_to_element.ts → utils/ui/index.ts}

@@ -1,4 +1,76 @@
-import { UIElement, GetUITreeResponse, SwipeResponse } from '../types.js'
+import crypto from 'crypto'
+import { GetUITreeResponse, GetCurrentScreenResponse, UIElement, SwipeResponse } from '../../types.js'
+
+const ANDROID_STRUCTURAL_TYPES = ['Window','Application','View','ViewGroup','LinearLayout','FrameLayout','RelativeLayout','ScrollView','RecyclerView','TextView','ImageView']
+const IOS_STRUCTURAL_TYPES = ['Window','Application','View','ViewController','UITableView','UICollectionView','UILabel','UIImageView','UIView','UIWindow','UIStackView','UITextView','UITableViewCell']
+
+function isDynamicText(t?: string): boolean {
+  if (!t) return false
+  const txt = t.trim()
+  if (!txt) return false
+  if (/\b\d{1,2}:\d{2}\b/.test(txt)) return true
+  if (/\b\d{4}-\d{2}-\d{2}\b/.test(txt)) return true
+  if (/^\d+(?:\.\d+)?%$/.test(txt)) return true
+  if (/^\d+$/.test(txt)) return true
+  if (/^[\d,]{1,10}$/.test(txt)) return true
+  return false
+}
+
+function normalizeElement(e: UIElement) {
+  return {
+    type: (e.type || '').toString(),
+    resourceId: (e.resourceId || '').toString(),
+    text: typeof e.text === 'string' ? (isDynamicText(e.text) ? '' : e.text.trim().toLowerCase()) : '',
+    contentDesc: (e.contentDescription || '').toString(),
+    bounds: Array.isArray(e.bounds) ? e.bounds.slice(0,4).map((n:any)=>Number(n)||0) : [0,0,0,0]
+  }
+}
+
+export function computeScreenFingerprint(tree: GetUITreeResponse, current: GetCurrentScreenResponse | null, platform: 'android' | 'ios', limit: number = 50): { fingerprint: string | null; activity?: string; error?: string } {
+  try {
+    if (!tree || (tree as any).error) return { fingerprint: null, error: (tree as any).error }
+
+    const activity = current && (current.activity || (current as any).shortActivity) ? (current.activity || (current as any).shortActivity) : ''
+
+    const candidates: UIElement[] = (tree.elements || []).filter(e => {
+      if (!e) return false
+      if (!e.visible) return false
+      const hasStableText = typeof e.text === 'string' && e.text.trim().length > 0
+      const hasResource = !!e.resourceId
+      const interactable = !!e.clickable || !!e.enabled
+      const structuralList = platform === 'android' ? ANDROID_STRUCTURAL_TYPES : IOS_STRUCTURAL_TYPES
+      const structurallySignificant = hasStableText || hasResource || structuralList.includes(e.type || '')
+      return interactable || structurallySignificant
+    }) as UIElement[]
+
+    const normalized = candidates.map(normalizeElement)
+
+    const filteredNormalized = normalized.filter(e => (e.text && e.text.length > 0) || (e.resourceId && e.resourceId.length > 0) || (e.contentDesc && e.contentDesc.length > 0))
+
+    filteredNormalized.sort((a,b) => {
+      const ay = (a.bounds && a.bounds[1]) || 0
+      const by = (b.bounds && b.bounds[1]) || 0
+      if (ay !== by) return ay - by
+      const ax = (a.bounds && a.bounds[0]) || 0
+      const bx = (b.bounds && b.bounds[0]) || 0
+      return ax - bx
+    })
+
+    const limited = filteredNormalized.slice(0, Math.max(0, limit))
+
+    const payload = {
+      activity: platform === 'android' ? (activity || '') : '',
+      resolution: (tree as any).resolution || { width: 0, height: 0 },
+      elements: limited.map(e => ({ type: e.type, resourceId: e.resourceId, text: e.text, contentDesc: e.contentDesc }))
+    }
+
+    const combined = JSON.stringify(payload)
+    const hash = crypto.createHash('sha256').update(combined).digest('hex')
+    return { fingerprint: hash, activity: activity }
+  } catch (e) {
+    return { fingerprint: null, error: e instanceof Error ? e.message : String(e) }
+  }
+}
 
 export interface ScrollSelector { text?: string; resourceId?: string; contentDesc?: string; className?: string }
 
@@ -84,7 +156,6 @@ export async function scrollToElementShared(opts: {
     try {
       await swipe(x1, y1, x2, y2, duration, deviceId)
     } catch (e) {
-      // Log swipe failures to aid debugging but don't fail the overall flow
       try { console.warn(`scrollToElement swipe failed: ${e instanceof Error ? e.message : String(e)}`) } catch {}
     }
 

package/test/{device/interact → interact/device}/smoke-test.ts

@@ -1,7 +1,6 @@
-import { AndroidObserve } from "../../src/android/observe.js";
-import { AndroidInteract } from "../../src/android/interact.js";
-import { iOSObserve } from "../../src/ios/observe.js";
-import { iOSInteract } from "../../src/ios/interact.js";
+import { AndroidObserve, iOSObserve } from "../../src/observe/index.js";
+import { AndroidInteract } from "../../src/interact/index.js";
+import { iOSInteract } from "../../src/interact/index.js";
 import fs from "fs/promises";
 
 const androidObserve = new AndroidObserve();

package/test/interact/unit/wait_for_screen_change.test.ts

@@ -0,0 +1,32 @@
+import { ToolsInteract } from '../../../src/interact/index.js'
+import * as Observe from '../../../src/observe/index.js'
+
+const original = (Observe as any).ToolsObserve.getScreenFingerprintHandler
+
+async function runTests() {
+  console.log('Starting tests for wait_for_screen_change...')
+
+  // Test 1: Immediate change
+  let seq1: Array<string | null> = ['B','B']
+  ;(Observe as any).ToolsObserve.getScreenFingerprintHandler = async () => ({ fingerprint: seq1.length ? seq1.shift() : null })
+  const start1 = Date.now()
+  const res1 = await ToolsInteract.waitForScreenChangeHandler({ platform: 'android', previousFingerprint: 'A', timeoutMs: 2000, pollIntervalMs: 50 })
+  const elapsed1 = Date.now() - start1
+  console.log('Test 1: Immediate change ->', (res1 && (res1 as any).success === true && (res1 as any).newFingerprint === 'B') ? 'PASS' : 'FAIL', 'Elapsed:', elapsed1, 'ms')
+
+  // Test 2: Transient nulls then stable change
+  let seq2: Array<string | null> = [null, null, 'B', 'B']
+  ;(Observe as any).ToolsObserve.getScreenFingerprintHandler = async () => ({ fingerprint: seq2.length ? seq2.shift() : 'B' })
+  const res2 = await ToolsInteract.waitForScreenChangeHandler({ platform: 'android', previousFingerprint: 'A', timeoutMs: 3000, pollIntervalMs: 50 })
+  console.log('Test 2: Transient nulls ->', (res2 && (res2 as any).success === true && (res2 as any).newFingerprint === 'B') ? 'PASS' : 'FAIL')
+
+  // Test 3: Timeout
+  ;(Observe as any).ToolsObserve.getScreenFingerprintHandler = async () => ({ fingerprint: 'A' })
+  const res3 = await ToolsInteract.waitForScreenChangeHandler({ platform: 'android', previousFingerprint: 'A', timeoutMs: 300, pollIntervalMs: 50 })
+  console.log('Test 3: Timeout ->', (res3 && (res3 as any).success === false && (res3 as any).reason === 'timeout') ? 'PASS' : 'FAIL')
+
+  // Restore original
+  ;(Observe as any).ToolsObserve.getScreenFingerprintHandler = original
+}
+
+runTests().catch(console.error)

package/test/{device/manage → manage/device}/run-install-android.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { AndroidManage } from '../../../dist/android/manage.js'
+import { AndroidManage } from '../../../dist/utils/android/manage.js'
 
 async function main() {
   const [, , appPath, deviceId] = process.argv

package/test/{device/manage → manage/device}/run-install-ios.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { iOSManage } from '../../../dist/ios/manage.js'
+import { iOSManage } from '../../../dist/utils/ios/manage.js'
 
 async function main() {
   const [, , appPath, deviceId] = process.argv

package/test/{device/manage → manage/device}/run-install-kmp.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { ToolsManage } from '../../../dist/tools/manage.js'
+import { ToolsManage } from '../../../dist/manage/index.js'
 import path from 'path'
 
 async function main() {

package/test/{unit/manage → manage/unit}/build.test.ts

@@ -57,7 +57,7 @@ process.exit(0)
   // Prefer explicit XCODEBUILD_PATH to ensure deterministic behavior
   process.env.XCODEBUILD_PATH = xcodePath
 
-  const { ToolsManage } = await import('../../../src/tools/manage.js')
+  const { ToolsManage } = await import('../../../src/manage/index.js')
 
   try {
     const ares = await ToolsManage.buildAppHandler({ platform: 'android', projectPath: androidProject })

package/test/{unit/manage → manage/unit}/build_and_install.test.ts

@@ -93,7 +93,7 @@ process.exit(0)
   process.env.PATH = `${binDir}:${origPath}`
   process.env.XCRUN_PATH = simctlPath
 
-  const { ToolsManage } = await import('../../../src/tools/manage.js')
+  const { ToolsManage } = await import('../../../src/manage/index.js')
 
   try {
     // Android build_and_install