mobile-debug-mcp 0.15.0 → 0.16.0

package/dist/interact/android.js

@@ -1,6 +1,6 @@
 import { execAdb, getAndroidDeviceMetadata, getDeviceInfo } from "../utils/android/utils.js";
 import { AndroidObserve } from "../observe/index.js";
-import { scrollToElementShared } from "../interact/shared/scroll_to_element.js";
+import { scrollToElementShared } from "../utils/ui/index.js";
 export class AndroidInteract {
     observe = new AndroidObserve();
     async waitForElement(text, timeout, deviceId) {

package/dist/interact/index.js

@@ -2,6 +2,7 @@ import { AndroidInteract } from './android.js';
 import { iOSInteract } from './ios.js';
 export { AndroidInteract, iOSInteract };
 import { resolveTargetDevice } from '../utils/resolve-device.js';
+import { ToolsObserve } from '../observe/index.js';
 export class ToolsInteract {
     static async getInteractionService(platform, deviceId) {
         const effectivePlatform = platform || 'android';
@@ -34,4 +35,42 @@ export class ToolsInteract {
         const { interact, resolved } = await ToolsInteract.getInteractionService(platform, deviceId);
         return await interact.scrollToElement(selector, direction, maxScrolls, scrollAmount, resolved.id);
     }
+    static async waitForScreenChangeHandler({ platform, previousFingerprint, timeoutMs = 5000, pollIntervalMs = 300, deviceId }) {
+        const start = Date.now();
+        let lastFingerprint = null;
+        while (Date.now() - start < timeoutMs) {
+            try {
+                const res = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId });
+                const fp = res?.fingerprint ?? null;
+                if (fp === null || fp === undefined) {
+                    lastFingerprint = null;
+                    await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
+                    continue;
+                }
+                lastFingerprint = fp;
+                if (fp !== previousFingerprint) {
+                    // Stability confirmation
+                    await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
+                    try {
+                        const confirmRes = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId });
+                        const confirmFp = confirmRes?.fingerprint ?? null;
+                        if (confirmFp === fp) {
+                            return { success: true, newFingerprint: fp, elapsedMs: Date.now() - start };
+                        }
+                        lastFingerprint = confirmFp;
+                        continue;
+                    }
+                    catch {
+                        // ignore and continue polling
+                        continue;
+                    }
+                }
+            }
+            catch {
+                // ignore transient errors
+            }
+            await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
+        }
+        return { success: false, reason: 'timeout', lastFingerprint, elapsedMs: Date.now() - start };
+    }
 }

package/dist/interact/ios.js

@@ -1,7 +1,7 @@
 import { spawn } from "child_process";
 import { getIOSDeviceMetadata, getIdbCmd, isIDBInstalled } from "../utils/ios/utils.js";
 import { iOSObserve } from "../observe/index.js";
-import { scrollToElementShared } from "../interact/shared/scroll_to_element.js";
+import { scrollToElementShared } from "../utils/ui/index.js";
 export class iOSInteract {
     observe = new iOSObserve();
     async waitForElement(text, timeout, deviceId = "booted") {

package/dist/interact/shared/fingerprint.js

@@ -1,72 +1 @@
-import crypto from 'crypto';
-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) {
-    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) {
-    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) => Number(n) || 0) : [0, 0, 0, 0]
-    };
-}
-export function computeScreenFingerprint(tree, current, platform, limit = 50) {
-    try {
-        if (!tree || tree.error)
-            return { fingerprint: null, error: tree.error };
-        const activity = current && (current.activity || current.shortActivity) ? (current.activity || current.shortActivity) : '';
-        const candidates = (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;
-        });
-        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.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 { computeScreenFingerprint } from '../../utils/ui/index.js';

package/dist/interact/shared/scroll_to_element.js

@@ -1,98 +1 @@
-export async function scrollToElementShared(opts) {
-    const { selector, direction = 'down', maxScrolls = 10, scrollAmount = 0.7, deviceId, fetchTree, swipe, stabilizationDelayMs = 350 } = opts;
-    const matchElement = (el) => {
-        if (!el)
-            return false;
-        if (selector.text !== undefined && selector.text !== el.text)
-            return false;
-        if (selector.resourceId !== undefined && selector.resourceId !== el.resourceId)
-            return false;
-        if (selector.contentDesc !== undefined && selector.contentDesc !== el.contentDescription)
-            return false;
-        if (selector.className !== undefined && selector.className !== el.type)
-            return false;
-        return true;
-    };
-    const isVisible = (el, resolution) => {
-        if (!el)
-            return false;
-        if (el.visible === false)
-            return false;
-        if (!el.bounds || !resolution || !resolution.width || !resolution.height)
-            return (el.visible === undefined ? true : !!el.visible);
-        const [left, top, right, bottom] = el.bounds;
-        const withinY = bottom > 0 && top < resolution.height;
-        const withinX = right > 0 && left < resolution.width;
-        return withinX && withinY;
-    };
-    const findVisibleMatch = (elements, resolution) => {
-        if (!Array.isArray(elements))
-            return null;
-        for (const e of elements) {
-            if (matchElement(e) && isVisible(e, resolution))
-                return e;
-        }
-        return null;
-    };
-    // Initial check
-    let tree = await fetchTree();
-    if (tree.error)
-        return { success: false, reason: tree.error, scrollsPerformed: 0 };
-    let found = findVisibleMatch(tree.elements, tree.resolution);
-    if (found) {
-        return { success: true, element: { text: found.text, resourceId: found.resourceId, bounds: found.bounds }, scrollsPerformed: 0 };
-    }
-    const fingerprintOf = (t) => {
-        try {
-            return JSON.stringify((t.elements || []).map((e) => ({ text: e.text, resourceId: e.resourceId, bounds: e.bounds })));
-        }
-        catch {
-            return '';
-        }
-    };
-    let prevFingerprint = fingerprintOf(tree);
-    const width = (tree.resolution && tree.resolution.width) ? tree.resolution.width : 0;
-    const height = (tree.resolution && tree.resolution.height) ? tree.resolution.height : 0;
-    const centerX = Math.round(width / 2) || 50;
-    const clampPct = (v) => Math.max(0.05, Math.min(0.95, v));
-    const computeCoords = () => {
-        const defaultStart = direction === 'down' ? 0.8 : 0.2;
-        const startPct = clampPct(defaultStart);
-        const endPct = clampPct(defaultStart + (direction === 'down' ? -scrollAmount : scrollAmount));
-        const x1 = centerX;
-        const x2 = centerX;
-        const y1 = Math.round((height || 100) * startPct);
-        const y2 = Math.round((height || 100) * endPct);
-        return { x1, y1, x2, y2 };
-    };
-    const duration = 300;
-    let scrollsPerformed = 0;
-    for (let i = 0; i < maxScrolls; i++) {
-        const { x1, y1, x2, y2 } = computeCoords();
-        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 { }
-        }
-        scrollsPerformed++;
-        await new Promise(resolve => setTimeout(resolve, stabilizationDelayMs));
-        tree = await fetchTree();
-        if (tree.error)
-            return { success: false, reason: tree.error, scrollsPerformed: scrollsPerformed };
-        found = findVisibleMatch(tree.elements, tree.resolution);
-        if (found) {
-            return { success: true, element: { text: found.text, resourceId: found.resourceId, bounds: found.bounds }, scrollsPerformed };
-        }
-        const fp = fingerprintOf(tree);
-        if (fp === prevFingerprint) {
-            return { success: false, reason: 'UI unchanged after scroll; likely end of list', scrollsPerformed: scrollsPerformed };
-        }
-        prevFingerprint = fp;
-    }
-    return { success: false, reason: 'Element not found after scrolling', scrollsPerformed: scrollsPerformed };
-}
+export { scrollToElementShared } from '../../utils/ui/index.js';

package/dist/observe/android.js

@@ -4,7 +4,7 @@ import { getAdbCmd, execAdb, getAndroidDeviceMetadata, getDeviceInfo, delay, get
 import { createWriteStream } from "fs";
 import { promises as fsPromises } from "fs";
 import path from "path";
-import { computeScreenFingerprint } from "../interact/shared/fingerprint.js";
+import { computeScreenFingerprint } from "../utils/ui/index.js";
 const activeLogStreams = new Map();
 export class AndroidObserve {
     async getDeviceMetadata(appId, deviceId) {

package/dist/observe/ios.js

@@ -4,7 +4,7 @@ import { execCommand, getIOSDeviceMetadata, validateBundleId, getIdbCmd, getXcru
 import { createWriteStream, promises as fsPromises } from 'fs';
 import path from 'path';
 import { parseLogLine } from '../utils/android/utils.js';
-import { computeScreenFingerprint } from '../interact/shared/fingerprint.js';
+import { computeScreenFingerprint } from '../utils/ui/index.js';
 const delay = (ms) => new Promise(resolve => setTimeout(resolve, ms));
 function parseIDBFrame(frame) {
     if (!frame)

package/dist/server.js

@@ -273,6 +273,21 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 }
             }
         },
+        {
+            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.",
@@ -556,6 +571,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const res = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId });
             return wrapResponse(res);
         }
+        if (name === "wait_for_screen_change") {
+            const { platform, previousFingerprint, timeoutMs, pollIntervalMs, deviceId } = (args || {});
+            const res = await ToolsInteract.waitForScreenChangeHandler({ platform, previousFingerprint, timeoutMs, pollIntervalMs, deviceId });
+            return wrapResponse(res);
+        }
         if (name === "wait_for_element") {
             const { platform, text, timeout, deviceId } = (args || {});
             const res = await ToolsInteract.waitForElementHandler({ platform, text, timeout, deviceId });

package/dist/utils/android/utils.js

@@ -1,7 +1,7 @@
-import { spawn } from 'child_process';
 import { promises as fsPromises, existsSync } from 'fs';
 import path from 'path';
 import { detectJavaHome } from '../java.js';
+import { execCmd } from '../exec.js';
 export function getAdbCmd() { return process.env.ADB_PATH || 'adb'; }
 /**
  * Prepare Gradle execution options for building an Android project.
@@ -76,76 +76,20 @@ function getAdbTimeout(args, customTimeout) {
         return 20000;
     return 120000;
 }
-export function execAdb(args, deviceId, options = {}) {
+export async function execAdb(args, deviceId, options = {}) {
     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, 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, deviceId, options = {}) {
+export async function spawnAdb(args, deviceId, options = {}) {
     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, 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, metadata = {}) {
     return {

package/dist/utils/exec.js

@@ -0,0 +1,34 @@
+import { spawn } from 'child_process';
+export async function execCmd(cmd, args, opts = {}) {
+    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/dist/utils/ui/index.js

@@ -0,0 +1,169 @@
+import crypto from 'crypto';
+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) {
+    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) {
+    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) => Number(n) || 0) : [0, 0, 0, 0]
+    };
+}
+export function computeScreenFingerprint(tree, current, platform, limit = 50) {
+    try {
+        if (!tree || tree.error)
+            return { fingerprint: null, error: tree.error };
+        const activity = current && (current.activity || current.shortActivity) ? (current.activity || current.shortActivity) : '';
+        const candidates = (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;
+        });
+        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.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 async function scrollToElementShared(opts) {
+    const { selector, direction = 'down', maxScrolls = 10, scrollAmount = 0.7, deviceId, fetchTree, swipe, stabilizationDelayMs = 350 } = opts;
+    const matchElement = (el) => {
+        if (!el)
+            return false;
+        if (selector.text !== undefined && selector.text !== el.text)
+            return false;
+        if (selector.resourceId !== undefined && selector.resourceId !== el.resourceId)
+            return false;
+        if (selector.contentDesc !== undefined && selector.contentDesc !== el.contentDescription)
+            return false;
+        if (selector.className !== undefined && selector.className !== el.type)
+            return false;
+        return true;
+    };
+    const isVisible = (el, resolution) => {
+        if (!el)
+            return false;
+        if (el.visible === false)
+            return false;
+        if (!el.bounds || !resolution || !resolution.width || !resolution.height)
+            return (el.visible === undefined ? true : !!el.visible);
+        const [left, top, right, bottom] = el.bounds;
+        const withinY = bottom > 0 && top < resolution.height;
+        const withinX = right > 0 && left < resolution.width;
+        return withinX && withinY;
+    };
+    const findVisibleMatch = (elements, resolution) => {
+        if (!Array.isArray(elements))
+            return null;
+        for (const e of elements) {
+            if (matchElement(e) && isVisible(e, resolution))
+                return e;
+        }
+        return null;
+    };
+    // Initial check
+    let tree = await fetchTree();
+    if (tree.error)
+        return { success: false, reason: tree.error, scrollsPerformed: 0 };
+    let found = findVisibleMatch(tree.elements, tree.resolution);
+    if (found) {
+        return { success: true, element: { text: found.text, resourceId: found.resourceId, bounds: found.bounds }, scrollsPerformed: 0 };
+    }
+    const fingerprintOf = (t) => {
+        try {
+            return JSON.stringify((t.elements || []).map((e) => ({ text: e.text, resourceId: e.resourceId, bounds: e.bounds })));
+        }
+        catch {
+            return '';
+        }
+    };
+    let prevFingerprint = fingerprintOf(tree);
+    const width = (tree.resolution && tree.resolution.width) ? tree.resolution.width : 0;
+    const height = (tree.resolution && tree.resolution.height) ? tree.resolution.height : 0;
+    const centerX = Math.round(width / 2) || 50;
+    const clampPct = (v) => Math.max(0.05, Math.min(0.95, v));
+    const computeCoords = () => {
+        const defaultStart = direction === 'down' ? 0.8 : 0.2;
+        const startPct = clampPct(defaultStart);
+        const endPct = clampPct(defaultStart + (direction === 'down' ? -scrollAmount : scrollAmount));
+        const x1 = centerX;
+        const x2 = centerX;
+        const y1 = Math.round((height || 100) * startPct);
+        const y2 = Math.round((height || 100) * endPct);
+        return { x1, y1, x2, y2 };
+    };
+    const duration = 300;
+    let scrollsPerformed = 0;
+    for (let i = 0; i < maxScrolls; i++) {
+        const { x1, y1, x2, y2 } = computeCoords();
+        try {
+            await swipe(x1, y1, x2, y2, duration, deviceId);
+        }
+        catch (e) {
+            try {
+                console.warn(`scrollToElement swipe failed: ${e instanceof Error ? e.message : String(e)}`);
+            }
+            catch { }
+        }
+        scrollsPerformed++;
+        await new Promise(resolve => setTimeout(resolve, stabilizationDelayMs));
+        tree = await fetchTree();
+        if (tree.error)
+            return { success: false, reason: tree.error, scrollsPerformed: scrollsPerformed };
+        found = findVisibleMatch(tree.elements, tree.resolution);
+        if (found) {
+            return { success: true, element: { text: found.text, resourceId: found.resourceId, bounds: found.bounds }, scrollsPerformed };
+        }
+        const fp = fingerprintOf(tree);
+        if (fp === prevFingerprint) {
+            return { success: false, reason: 'UI unchanged after scroll; likely end of list', scrollsPerformed: scrollsPerformed };
+        }
+        prevFingerprint = fp;
+    }
+    return { success: false, reason: 'Element not found after scrolling', scrollsPerformed: scrollsPerformed };
+}

package/docs/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 All notable changes to the **Mobile Debug MCP** project will be documented in this file.
 
+## [0.16.0]
+- Added `wait_for_screen_change` interact tool: polls the platform-specific `get_screen_fingerprint` until it differs from a provided `previousFingerprint`, with configurable `timeoutMs` and `pollIntervalMs` and an optional stability confirmation poll to avoid reacting to transient UI flickers. Implemented at the interact layer and delegates fingerprinting to the observe implementations (Android/iOS).
+- Added unit tests covering immediate change, transient null fingerprints, stability confirmation and timeout behavior: `test/interact/unit/wait_for_screen_change.test.ts`.
+
 ## [0.15.0]
 - Reorganised repository for cohesion: merged tool handlers into feature entrypoints (src/observe, src/interact, src/manage) and moved platform helpers and CLI tooling into src/utils/{android,ios,cli}.
 - Added computeScreenFingerprint utility used by observe/interact to normalise UI element significance across platforms (fingerprint shared between Android and iOS implementations).

package/docs/tools/interact.md

@@ -72,3 +72,32 @@ Notes:
 - Android swipe uses `adb shell input swipe` with screen percentage coordinates. iOS swipe uses `idb ui swipe` command; note `idb` swipe does not accept a duration argument.
 - Unit tests are located at `test/unit/observe/scroll_to_element.test.ts` and device runners at `test/device/observe/`.
 
+---
+
+## wait_for_screen_change
+
+Description:
+- Waits until the current screen fingerprint differs from the provided `previousFingerprint`. Useful after taps, navigation, or other interactions that should change the visible UI.
+
+Input example:
+```
+{ "platform": "android", "previousFingerprint": "<hex-fingerprint>", "timeoutMs": 5000, "pollIntervalMs": 300, "deviceId": "emulator-5554" }
+```
+
+Success response example:
+```
+{ "success": true, "newFingerprint": "<hex-fingerprint>", "elapsedMs": 420 }
+```
+
+Failure (timeout) example:
+```
+{ "success": false, "reason": "timeout", "lastFingerprint": "<hex-fingerprint>", "elapsedMs": 5000 }
+```
+
+Notes:
+- Always compares to the original `previousFingerprint` (baseline is not updated during polling).
+- Treats `null` fingerprints as transient; continues polling rather than returning success.
+- Includes a stability confirmation: after detecting a different fingerprint it waits one additional poll interval and confirms the fingerprint is stable before returning success to avoid reacting to transient flickers or animation frames.
+- Default `timeoutMs` is 5000ms and default `pollIntervalMs` is 300ms; callers may override these.
+- Implemented as an interact-level tool and delegates platform-specific fingerprint calculation to the observe layer (`get_screen_fingerprint`).
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-debug-mcp",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "MCP server for mobile app debugging (Android + iOS), with focus on security and reliability",
   "type": "module",
   "bin": {

package/src/interact/android.ts

@@ -1,7 +1,7 @@
 import { WaitForElementResponse, 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 "../interact/shared/scroll_to_element.js"
+import { scrollToElementShared } from "../utils/ui/index.js"
 
 
 export class AndroidInteract {

package/src/interact/index.ts

@@ -3,6 +3,7 @@ import { iOSInteract } from './ios.js';
 export { AndroidInteract, iOSInteract };
 
 import { resolveTargetDevice } from '../utils/resolve-device.js'
+import { ToolsObserve } from '../observe/index.js'
 
 export class ToolsInteract {
 
@@ -44,4 +45,46 @@ export class ToolsInteract {
     return await interact.scrollToElement(selector, direction, maxScrolls, scrollAmount, resolved.id)
   }
 
+  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
+
+    while (Date.now() - start < timeoutMs) {
+      try {
+        const res = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId })
+        const fp = (res as any)?.fingerprint ?? null
+        if (fp === null || fp === undefined) {
+          lastFingerprint = null
+          await new Promise(resolve => setTimeout(resolve, pollIntervalMs))
+          continue
+        }
+
+        lastFingerprint = fp
+
+        if (fp !== previousFingerprint) {
+          // Stability confirmation
+          await new Promise(resolve => setTimeout(resolve, pollIntervalMs))
+          try {
+            const confirmRes = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId })
+            const confirmFp = (confirmRes as any)?.fingerprint ?? null
+            if (confirmFp === fp) {
+              return { success: true, newFingerprint: fp, elapsedMs: Date.now() - start }
+            }
+            lastFingerprint = confirmFp
+            continue
+          } catch {
+            // ignore and continue polling
+            continue
+          }
+        }
+      } catch {
+        // ignore transient errors
+      }
+
+      await new Promise(resolve => setTimeout(resolve, pollIntervalMs))
+    }
+
+    return { success: false, reason: 'timeout', lastFingerprint, elapsedMs: Date.now() - start }
+  }
+
 }

package/src/interact/ios.ts

@@ -2,7 +2,7 @@ import { spawn } from "child_process"
 import { WaitForElementResponse, TapResponse, SwipeResponse } from "../types.js"
 import { getIOSDeviceMetadata, getIdbCmd, isIDBInstalled } from "../utils/ios/utils.js"
 import { iOSObserve } from "../observe/index.js"
-import { scrollToElementShared } from "../interact/shared/scroll_to_element.js"
+import { scrollToElementShared } from "../utils/ui/index.js"
 
 export class iOSInteract {
   private observe = new iOSObserve();

package/src/observe/android.ts

@@ -5,7 +5,7 @@ import { getAdbCmd, execAdb, getAndroidDeviceMetadata, getDeviceInfo, delay, get
 import { createWriteStream } from "fs"
 import { promises as fsPromises } from "fs"
 import path from "path"
-import { computeScreenFingerprint } from "../interact/shared/fingerprint.js"
+import { computeScreenFingerprint } from "../utils/ui/index.js"
 
 const activeLogStreams: Map<string, { proc: any, file: string }> = new Map()
 

package/src/observe/ios.ts

@@ -5,7 +5,7 @@ import { execCommand, getIOSDeviceMetadata, validateBundleId, getIdbCmd, getXcru
 import { createWriteStream, promises as fsPromises } from 'fs'
 import path from 'path'
 import { parseLogLine } from '../utils/android/utils.js'
-import { computeScreenFingerprint } from '../interact/shared/fingerprint.js'
+import { computeScreenFingerprint } from '../utils/ui/index.js'
 
 const delay = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));
 

package/src/server.ts

@@ -294,6 +294,21 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         }
       }
     },
+    {
+      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.",
@@ -322,6 +337,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         required: ["platform", "text"]
       }
     },
+
     {
       name: "tap",
       description: "Simulate a finger tap on the device screen at specific coordinates.",
@@ -596,6 +612,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       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 })

package/src/types.ts

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

package/src/utils/android/utils.ts

@@ -1,8 +1,8 @@
-import { spawn } from 'child_process'
 import { DeviceInfo, UIElement } from "../../types.js"
 import { promises as fsPromises, existsSync } from 'fs'
 import path from 'path'
 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/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/{interact/shared/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/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/unit/index.ts

@@ -10,5 +10,6 @@ import '../manage/unit/build_and_install.test.ts'
 import '../manage/unit/diagnostics.test.ts'
 import '../manage/unit/detection.test.ts'
 import '../manage/unit/mcp_disable_autodetect.test.ts'
+import '../interact/unit/wait_for_screen_change.test.ts'
 
 console.log('Unit tests loaded.')

package/src/interact/shared/fingerprint.ts

@@ -1,73 +0,0 @@
-import crypto from 'crypto'
-import { GetUITreeResponse, GetCurrentScreenResponse, UIElement } 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) }
-  }
-}