mobile-debug-mcp 0.13.0 → 0.15.0

package/dist/utils/ios/utils.js

@@ -0,0 +1,301 @@
+import { execFile, spawn, execSync, spawnSync } from "child_process";
+import { promises as fsPromises } from 'fs';
+import path from 'path';
+import { makeEnvSnapshot } from '../diagnostics.js';
+export function getXcrunCmd() { return process.env.XCRUN_PATH || 'xcrun'; }
+export function getConfiguredIdbPath() {
+    if (process.env.MCP_IDB_PATH)
+        return process.env.MCP_IDB_PATH;
+    if (process.env.IDB_PATH)
+        return process.env.IDB_PATH;
+    const cfgPaths = [
+        process.env.MCP_CONFIG_PATH || (process.env.HOME ? `${process.env.HOME}/.mcp/config.json` : ''),
+        `${process.cwd()}/mcp.config.json`
+    ];
+    try {
+        const fs = require('fs');
+        for (const p of cfgPaths) {
+            if (!p)
+                continue;
+            try {
+                if (fs.existsSync(p)) {
+                    const raw = fs.readFileSync(p, 'utf8');
+                    const json = JSON.parse(raw);
+                    if (json) {
+                        if (json.idbPath)
+                            return json.idbPath;
+                        if (json.IDB_PATH)
+                            return json.IDB_PATH;
+                    }
+                }
+            }
+            catch { }
+        }
+    }
+    catch { }
+    return undefined;
+}
+export function getIdbCmd() {
+    const cfg = getConfiguredIdbPath();
+    if (cfg)
+        return cfg;
+    if (process.env.IDB_PATH)
+        return process.env.IDB_PATH;
+    try {
+        const p = execSync('which idb', { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+        if (p)
+            return p;
+    }
+    catch { }
+    try {
+        const p2 = execSync('command -v idb', { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+        if (p2)
+            return p2;
+    }
+    catch { }
+    // check common user locations
+    const common = [
+        `${process.env.HOME}/Library/Python/3.9/bin/idb`,
+        `${process.env.HOME}/Library/Python/3.10/bin/idb`,
+        '/opt/homebrew/bin/idb',
+        '/usr/local/bin/idb',
+    ];
+    for (const c of common) {
+        try {
+            execSync(`test -x ${c}`, { stdio: ['ignore', 'pipe', 'ignore'] });
+            return c;
+        }
+        catch { }
+    }
+    return 'idb';
+}
+export async function isIDBInstalled() {
+    const cmd = getIdbCmd();
+    try {
+        execSync(`command -v ${cmd}`, { stdio: ['ignore', 'pipe', 'ignore'] });
+        return true;
+    }
+    catch {
+        try {
+            execSync(`${cmd} list-targets --json`, { stdio: ['ignore', 'pipe', 'ignore'], timeout: 2000 });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+// Validate bundle ID to prevent any potential injection or invalid characters
+export function validateBundleId(bundleId) {
+    if (!bundleId)
+        return;
+    // Allow alphanumeric, dots, hyphens, and underscores.
+    if (!/^[a-zA-Z0-9.\-_]+$/.test(bundleId)) {
+        throw new Error(`Invalid Bundle ID: ${bundleId}. Must contain only alphanumeric characters, dots, hyphens, or underscores.`);
+    }
+}
+export function execCommand(args, deviceId = "booted") {
+    return new Promise((resolve, reject) => {
+        // Use spawn for better stream control and consistency with Android implementation
+        const child = spawn(getXcrunCmd(), args);
+        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 DEFAULT_XCRUN_LOG_TIMEOUT = parseInt(process.env.MCP_XCRUN_LOG_TIMEOUT || '', 10) || 30000; // env (ms) or default 30s
+        const DEFAULT_XCRUN_CMD_TIMEOUT = parseInt(process.env.MCP_XCRUN_TIMEOUT || '', 10) || 60000; // env (ms) or default 60s
+        const timeoutMs = args.includes('log') ? DEFAULT_XCRUN_LOG_TIMEOUT : DEFAULT_XCRUN_CMD_TIMEOUT; // choose appropriate timeout
+        const timeout = setTimeout(() => {
+            child.kill();
+            reject(new Error(`Command timed out after ${timeoutMs}ms: ${getXcrunCmd()} ${args.join(' ')}`));
+        }, timeoutMs);
+        child.on('close', (code) => {
+            clearTimeout(timeout);
+            if (code !== 0) {
+                reject(new Error(stderr.trim() || `Command failed with code ${code}`));
+            }
+            else {
+                resolve({ output: stdout.trim(), device: { platform: "ios", id: deviceId } });
+            }
+        });
+        child.on('error', (err) => {
+            clearTimeout(timeout);
+            reject(err);
+        });
+    });
+}
+export function execCommandWithDiagnostics(args, deviceId = "booted") {
+    // Run synchronously to capture stdout/stderr and exitCode reliably for diagnostics
+    const DEFAULT_XCRUN_LOG_TIMEOUT = parseInt(process.env.MCP_XCRUN_LOG_TIMEOUT || '', 10) || 30000;
+    const DEFAULT_XCRUN_CMD_TIMEOUT = parseInt(process.env.MCP_XCRUN_TIMEOUT || '', 10) || 60000;
+    const timeoutMs = args.includes('log') ? DEFAULT_XCRUN_LOG_TIMEOUT : DEFAULT_XCRUN_CMD_TIMEOUT;
+    const res = spawnSync(getXcrunCmd(), args, { encoding: 'utf8', timeout: timeoutMs });
+    const runResult = {
+        exitCode: typeof res.status === 'number' ? res.status : null,
+        stdout: res.stdout || '',
+        stderr: res.stderr || '',
+        envSnapshot: makeEnvSnapshot(['PATH', 'IDB_PATH', 'JAVA_HOME', 'HOME']),
+        command: getXcrunCmd(),
+        args,
+        deviceId
+    };
+    if (res.status !== 0) {
+        // include suggested fixes for common errors
+        const suggested = [];
+        if ((runResult.stderr || '').includes('xcodebuild: error')) {
+            suggested.push('Ensure the project/workspace path is correct and xcodebuild is installed and accessible.');
+        }
+        if ((runResult.stderr || '').includes('No such file or directory') || (runResult.stderr || '').includes('not found')) {
+            suggested.push('Check that Xcode Command Line Tools are installed and XCRUN_PATH is set if using non-standard location.');
+        }
+        // Return diagnostics object
+        return { runResult: { ...runResult, suggestedFixes: suggested } };
+    }
+    return { runResult: { ...runResult, suggestedFixes: [] } };
+}
+function parseRuntimeName(runtime) {
+    // Example: com.apple.CoreSimulator.SimRuntime.iOS-17-0 -> iOS 17.0
+    try {
+        const parts = runtime.split('.');
+        const lastPart = parts[parts.length - 1]; // e.g. "iOS-17-0"
+        // Split by hyphen to separate OS from version numbers
+        // e.g. "iOS-17-0" -> ["iOS", "17", "0"]
+        const segments = lastPart.split('-');
+        if (segments.length > 1) {
+            const os = segments[0]; // "iOS"
+            const version = segments.slice(1).join('.'); // "17.0"
+            return `${os} ${version}`;
+        }
+        return lastPart;
+    }
+    catch {
+        return runtime;
+    }
+}
+export async function findAppBundle(dir) {
+    const entries = await fsPromises.readdir(dir, { withFileTypes: true }).catch(() => []);
+    for (const e of entries) {
+        const full = path.join(dir, e.name);
+        if (e.isDirectory()) {
+            if (full.endsWith('.app'))
+                return full;
+            const found = await findAppBundle(full);
+            if (found)
+                return found;
+        }
+    }
+    return undefined;
+}
+export async function getIOSDeviceMetadata(deviceId = "booted") {
+    return new Promise((resolve) => {
+        // If deviceId is provided (and not "booted"), attempt to find that device among booted simulators.
+        execFile(getXcrunCmd(), ['simctl', 'list', 'devices', 'booted', '--json'], (err, stdout) => {
+            const fallback = {
+                platform: "ios",
+                id: deviceId,
+                osVersion: "Unknown",
+                model: "Simulator",
+                simulator: true,
+            };
+            if (err || !stdout) {
+                resolve(fallback);
+                return;
+            }
+            try {
+                const data = JSON.parse(stdout);
+                const devicesMap = data.devices || {};
+                for (const runtime in devicesMap) {
+                    const devices = devicesMap[runtime];
+                    if (Array.isArray(devices)) {
+                        for (const device of devices) {
+                            if (deviceId === "booted" || device.udid === deviceId) {
+                                resolve({
+                                    platform: "ios",
+                                    id: device.udid,
+                                    osVersion: parseRuntimeName(runtime),
+                                    model: device.name,
+                                    simulator: true,
+                                });
+                                return;
+                            }
+                        }
+                    }
+                }
+                resolve(fallback);
+            }
+            catch {
+                resolve(fallback);
+            }
+        });
+    });
+}
+export async function listIOSDevices(appId) {
+    return new Promise((resolve) => {
+        // Query all devices and separately query booted devices to mark them
+        execFile(getXcrunCmd(), ['simctl', 'list', 'devices', '--json'], (err, stdout) => {
+            if (err || !stdout)
+                return resolve([]);
+            try {
+                const data = JSON.parse(stdout);
+                const devicesMap = data.devices || {};
+                const out = [];
+                const checks = [];
+                // Get booted devices set
+                execFile(getXcrunCmd(), ['simctl', 'list', 'devices', 'booted', '--json'], (err2, stdout2) => {
+                    const bootedSet = new Set();
+                    if (!err2 && stdout2) {
+                        try {
+                            const bdata = JSON.parse(stdout2);
+                            const bmap = bdata.devices || {};
+                            for (const rt in bmap) {
+                                const devs = bmap[rt];
+                                if (Array.isArray(devs))
+                                    for (const d of devs)
+                                        bootedSet.add(d.udid);
+                            }
+                        }
+                        catch { }
+                    }
+                    for (const runtime in devicesMap) {
+                        const devices = devicesMap[runtime];
+                        if (Array.isArray(devices)) {
+                            for (const device of devices) {
+                                const info = {
+                                    platform: 'ios',
+                                    id: device.udid,
+                                    osVersion: parseRuntimeName(runtime),
+                                    model: device.name,
+                                    simulator: true,
+                                    booted: bootedSet.has(device.udid)
+                                };
+                                if (appId) {
+                                    // check if installed
+                                    const p = execCommand(['simctl', 'get_app_container', device.udid, appId, 'data'], device.udid)
+                                        .then(() => { info.appInstalled = true; })
+                                        .catch(() => { info.appInstalled = false; })
+                                        .then(() => { out.push(info); });
+                                    checks.push(p);
+                                }
+                                else {
+                                    out.push(info);
+                                }
+                            }
+                        }
+                    }
+                    Promise.all(checks).then(() => resolve(out)).catch(() => resolve(out));
+                });
+            }
+            catch {
+                resolve([]);
+            }
+        });
+    });
+}

package/dist/utils/resolve-device.js

@@ -1,5 +1,5 @@
-import { listAndroidDevices } from "../android/utils.js";
-import { listIOSDevices } from "../ios/utils.js";
+import { listAndroidDevices } from "./android/utils.js";
+import { listIOSDevices } from "./ios/utils.js";
 function parseNumericVersion(v) {
     if (!v)
         return 0;

package/docs/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to the **Mobile Debug MCP** project will be documented in this file.
 
+## [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).
+
+## [0.14.0]
+- Added `scroll_to_element` tool: platform-aware helper that scrolls until a UI element matching a selector is visible. Supports Android and iOS with configurable options: direction, maxScrolls, and scrollAmount. Includes unit tests and device runners under `test/device/` for manual E2E validation.
+- Moved scroll logic into platform-specific implementations (`src/android/interact.ts`, `src/ios/interact.ts`) and delegated from `src/tools/interact.ts` to centralise platform behaviour.
+- Fixed iOS `idb` swipe arguments and improved visibility detection by using element bounds and device resolution to avoid treating off-screen elements as visible.
+- Consolidated unit tests for `scroll_to_element` into `test/unit/observe/scroll_to_element.test.ts`, and removed older duplicate test files.
+
+
 ## [0.13.0]
 - Fixed a crash in the `start_app` tool by adding validation to ensure `appId` and `platform` are provided.
 

package/docs/tools/TOOLS.md

@@ -4,8 +4,8 @@ This repository groups tool docs into three areas aligned with the codebase: man
 
 See:
 
-- docs/manage.md — build, install and device management tools
-- docs/observe.md — logs, screenshots and UI inspection tools
-- docs/interact.md — UI interaction tools (tap, swipe, type, wait)
+- [mange](manage.md) — build, install and device management tools
+- [observe](observe.md) — logs, screenshots and UI inspection tools
+- [interact](interact.md) — UI interaction tools (tap, swipe, type, wait)
 
 For per-tool deep dives, open the linked files above.

package/docs/tools/interact.md

@@ -41,3 +41,34 @@ Notes:
 - swipe: `adb shell input swipe x1 y1 x2 y2 duration`.
 - type_text: `adb shell input text` (spaces encoded as %s) — may fail for special characters.
 - press_back: `adb shell input keyevent 4`.
+
+---
+
+## scroll_to_element
+
+Description:
+- Scrolls the UI until an element matching the provided selector becomes visible, or until a maximum number of scroll attempts is reached.
+- Delegates platform behaviour to Android and iOS implementations for reliable swipes and UI-tree checks.
+
+Input example:
+```
+{ "platform": "android", "selector": { "text": "Offscreen Test Element" }, "direction": "down", "maxScrolls": 10, "scrollAmount": 0.7, "deviceId": "emulator-5554" }
+```
+
+Response example (found):
+```
+{ "success": true, "reason": "element_found", "element": { /* element metadata */ }, "scrollsPerformed": 2 }
+```
+
+Response example (failure - unchanged UI):
+```
+{ "success": false, "reason": "ui_unchanged_after_scroll", "scrollsPerformed": 3 }
+```
+
+Notes:
+- Matching is exact on provided selector fields (text, resourceId, contentDesc, className).
+- Visibility check uses element.bounds intersecting the device resolution when available; falls back to the element.visible flag if bounds/resolution are missing.
+- The tool fingerprints the visible UI between scrolls; if the fingerprint doesn't change after a swipe the tool stops early assuming end-of-list.
+- 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/`.
+

package/docs/tools/observe.md

@@ -76,6 +76,30 @@ Response:
 
 ---
 
+## get_screen_fingerprint
+Generate a stable fingerprint representing the visible screen. Useful for detecting navigation changes, preventing loops, and synchronisation.
+
+Input (optional):
+
+```
+{ "platform": "android", "deviceId": "emulator-5554" }
+```
+
+Response:
+
+```json
+{ "fingerprint": "<sha256_hex>", "activity": "com.example.app.MainActivity" }
+```
+
+Notes:
+- Uses get_ui_tree and (on Android) get_current_screen as inputs.
+- Normalises visible, interactable or structurally significant elements (class/type, resourceId, text, contentDesc).
+- Trims and lowercases text, filters out likely dynamic values (timestamps, counters).
+- Sorts deterministically (top-to-bottom, left-to-right) and limits elements to 50.
+- Returns fingerprint: null and an error message if the UI tree or activity cannot be retrieved.
+
+---
+
 ## start_log_stream / read_log_stream / stop_log_stream
 Start a background adb logcat stream and retrieve parsed NDJSON entries.
 

package/package.json

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

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

@@ -1,6 +1,7 @@
 import { WaitForElementResponse, TapResponse, SwipeResponse, TypeTextResponse, PressBackResponse } from "../types.js"
-import { execAdb, getAndroidDeviceMetadata, getDeviceInfo } from "./utils.js"
-import { AndroidObserve } from "./observe.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"
 
 
 export class AndroidInteract {
@@ -88,4 +89,16 @@ export class AndroidInteract {
     }
   }
 
+  async scrollToElement(selector: { text?: string, resourceId?: string, contentDesc?: string, className?: string }, direction: 'down' | 'up' = 'down', maxScrolls = 10, scrollAmount = 0.7, deviceId?: string) {
+    return await scrollToElementShared({
+      selector,
+      direction,
+      maxScrolls,
+      scrollAmount,
+      deviceId,
+      fetchTree: async () => await this.observe.getUITree(deviceId),
+      swipe: async (x1: number, y1: number, x2: number, y2: number, duration: number, devId?: string) => await this.swipe(x1, y1, x2, y2, duration, devId)
+    })
+  }
+
 }

package/src/interact/index.ts

@@ -0,0 +1,47 @@
+import { AndroidInteract } from './android.js';
+import { iOSInteract } from './ios.js';
+export { AndroidInteract, iOSInteract };
+
+import { resolveTargetDevice } from '../utils/resolve-device.js'
+
+export class ToolsInteract {
+
+  private static async getInteractionService(platform?: 'android' | 'ios', deviceId?: string) {
+    const effectivePlatform = platform || 'android'
+    const resolved = await resolveTargetDevice({ platform: effectivePlatform as 'android' | 'ios', deviceId })
+    const interact = effectivePlatform === 'android' ? new AndroidInteract() : new iOSInteract()
+    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)
+  }
+
+  static async swipeHandler({ platform = 'android', x1, y1, x2, y2, duration, deviceId }: { platform?: 'android' | 'ios', x1: number, y1: number, x2: number, y2: number, duration: number, deviceId?: string }) {
+    const { interact, resolved } = await ToolsInteract.getInteractionService(platform, deviceId)
+    return await interact.swipe(x1, y1, x2, y2, duration, resolved.id)
+  }
+
+  static async typeTextHandler({ text, deviceId }: { text: string, deviceId?: string }) {
+    const resolved = await resolveTargetDevice({ platform: 'android', deviceId })
+    return await new AndroidInteract().typeText(text, resolved.id)
+  }
+
+  static async pressBackHandler({ deviceId }: { deviceId?: string }) {
+    const resolved = await resolveTargetDevice({ platform: 'android', deviceId })
+    return await new AndroidInteract().pressBack(resolved.id)
+  }
+
+  static async scrollToElementHandler({ platform, selector, direction = 'down', maxScrolls = 10, scrollAmount = 0.7, deviceId }: { platform: 'android' | 'ios', selector: { text?: string, resourceId?: string, contentDesc?: string, className?: string }, direction?: 'down' | 'up', maxScrolls?: number, scrollAmount?: number, deviceId?: string }) {
+    const { interact, resolved } = await ToolsInteract.getInteractionService(platform, deviceId)
+    return await interact.scrollToElement(selector, direction, maxScrolls, scrollAmount, resolved.id)
+  }
+
+}

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

@@ -1,7 +1,8 @@
 import { spawn } from "child_process"
-import { WaitForElementResponse, TapResponse } from "../types.js"
-import { getIOSDeviceMetadata, getIdbCmd, isIDBInstalled } from "./utils.js"
-import { iOSObserve } from "./observe.js"
+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"
 
 export class iOSInteract {
   private observe = new iOSObserve();
@@ -75,4 +76,58 @@ export class iOSInteract {
       return { device, success: false, x, y, error: e instanceof Error ? e.message : String(e) };
     }
   }
+
+  async swipe(x1: number, y1: number, x2: number, y2: number, duration: number, deviceId: string = "booted"): Promise<SwipeResponse> {
+    const device = await getIOSDeviceMetadata(deviceId);
+    // Use shared helper to detect idb
+    const idbExists = await isIDBInstalled();
+
+    if (!idbExists) {
+      return {
+        device,
+        success: false,
+        start: [x1, y1],
+        end: [x2, y2],
+        duration,
+        error: "iOS swipe requires 'idb' (iOS Device Bridge)."
+      }
+    }
+
+    try {
+      const targetUdid = (device.id && device.id !== 'booted') ? device.id : undefined;
+      // idb 'ui swipe' does not accept a duration parameter; use coordinates only
+      const args: string[] = ['ui', 'swipe', x1.toString(), y1.toString(), x2.toString(), y2.toString()];
+      if (targetUdid) {
+        args.push('--udid', targetUdid);
+      }
+
+      await new Promise<void>((resolve, reject) => {
+        const proc = spawn(getIdbCmd(), args);
+        let stderr = '';
+        proc.stderr.on('data', d => stderr += d.toString());
+        proc.on('close', code => {
+          if (code === 0) resolve();
+          else reject(new Error(`idb ui swipe failed: ${stderr}`));
+        });
+        proc.on('error', err => reject(err));
+      });
+
+      return { device, success: true, start: [x1, y1], end: [x2, y2], duration };
+    } catch (e) {
+      return { device, success: false, start: [x1, y1], end: [x2, y2], duration, error: e instanceof Error ? e.message : String(e) };
+    }
+  }
+
+  async scrollToElement(selector: { text?: string, resourceId?: string, contentDesc?: string, className?: string }, direction: 'down' | 'up' = 'down', maxScrolls = 10, scrollAmount = 0.7, deviceId: string = 'booted') {
+    return await scrollToElementShared({
+      selector,
+      direction,
+      maxScrolls,
+      scrollAmount,
+      deviceId,
+      fetchTree: async () => await this.observe.getUITree(deviceId),
+      swipe: async (x1: number, y1: number, x2: number, y2: number, duration: number, devId?: string) => await this.swipe(x1, y1, x2, y2, duration, devId)
+    })
+  }
 }
+

package/src/interact/shared/fingerprint.ts

@@ -0,0 +1,73 @@
+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) }
+  }
+}