mobile-debug-mcp 0.17.0 → 0.19.0

package/README.md

@@ -24,6 +24,8 @@ A minimal, secure MCP server for AI-assisted mobile development. Build, install,
   }
 }
 ```
+You will need to add ADB_PATH for Android and XCRUN_PATH and IDB_PATH for iOS.
+
 ## Usage
 
 Example: 

package/dist/interact/index.js

@@ -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';
+const STABLE_IDLE_MS = 1000;
 export class ToolsInteract {
     static async getInteractionService(platform, deviceId) {
         const effectivePlatform = platform || 'android';
@@ -35,6 +36,191 @@ export class ToolsInteract {
         const { interact, resolved } = await ToolsInteract.getInteractionService(platform, deviceId);
         return await interact.scrollToElement(selector, direction, maxScrolls, scrollAmount, resolved.id);
     }
+    static async findElementHandler({ query, exact = false, timeoutMs = 3000, platform, deviceId }) {
+        // Try to use observe layer to fetch the current UI tree and perform a fast semantic search
+        const start = Date.now();
+        const deadline = start + timeoutMs;
+        const normalize = (s) => (s === null || s === undefined) ? '' : String(s).toLowerCase().trim();
+        const q = normalize(query);
+        if (!q)
+            return { found: false, error: 'Empty query' };
+        let best = null;
+        let bestScore = 0;
+        const scoreElement = (el) => {
+            if (!el || !el.visible)
+                return 0;
+            const bounds = el.bounds || [0, 0, 0, 0];
+            if (!Array.isArray(bounds) || bounds.length < 4)
+                return 0;
+            const [l, t, r, b] = bounds;
+            if (r <= l || b <= t)
+                return 0;
+            // Do not early-return on non-interactable elements — score them so we can locate their clickable ancestor later
+            const interactable = !!(el.clickable || el.enabled || el.focusable);
+            const text = normalize(el.text ?? el.label ?? el.value ?? '');
+            const content = normalize(el.contentDescription ?? el.contentDesc ?? el.accessibilityLabel ?? '');
+            const resourceId = normalize(el.resourceId ?? el.resourceID ?? el.id ?? '');
+            const className = normalize(el.type ?? el.class ?? '');
+            let score = 0;
+            if (exact) {
+                if (text && text === q)
+                    score = 1.0;
+                else if (content && content === q)
+                    score = 0.95;
+            }
+            else {
+                if (text && text === q)
+                    score = 1.0;
+                else if (content && content === q)
+                    score = 0.95;
+                else if (text && text.includes(q))
+                    score = 0.6;
+                else if (content && content.includes(q))
+                    score = 0.55;
+                else if (resourceId && resourceId.includes(q))
+                    score = 0.7;
+                else if (className && className.includes(q))
+                    score = 0.3;
+            }
+            if (score > 0 && interactable)
+                score += 0.05;
+            return score;
+        };
+        while (Date.now() <= deadline) {
+            try {
+                const tree = await ToolsObserve.getUITreeHandler({ platform, deviceId });
+                if (tree && Array.isArray(tree.elements)) {
+                    const elements = tree.elements;
+                    for (let i = 0; i < elements.length; i++) {
+                        const el = elements[i];
+                        try {
+                            const s = scoreElement(el);
+                            const interactable = !!(el.clickable || el.enabled || el.focusable);
+                            if (s > bestScore) {
+                                bestScore = s;
+                                best = el;
+                                if (best) {
+                                    best._index = i;
+                                    best._interactable = interactable;
+                                }
+                            }
+                            if (bestScore >= 0.95)
+                                break;
+                        }
+                        catch (e) {
+                            console.error('Error scoring element:', e);
+                        }
+                    }
+                    if (bestScore >= 0.95)
+                        break;
+                }
+            }
+            catch (e) {
+                console.error('Error fetching UI tree:', e);
+            }
+            if (Date.now() > deadline)
+                break;
+            await new Promise(r => setTimeout(r, 100));
+        }
+        if (!best)
+            return { found: false, error: 'Element not found' };
+        // If the best match is not interactable, try to resolve an actionable ancestor.
+        try {
+            const tree = await ToolsObserve.getUITreeHandler({ platform, deviceId });
+            const elements = (tree && Array.isArray(tree.elements)) ? tree.elements : [];
+            let chosen = best;
+            const childBounds = Array.isArray(chosen?.bounds) ? chosen.bounds : null;
+            // Strategy 1: if parentId references an index, climb that chain
+            let resolvedAncestor = null;
+            if (childBounds && (chosen.parentId !== undefined && chosen.parentId !== null)) {
+                let cur = chosen;
+                let safety = 0;
+                while (cur && safety < 20 && !(cur.clickable || cur.focusable) && (cur.parentId !== undefined && cur.parentId !== null)) {
+                    let pid = cur.parentId;
+                    let idx = null;
+                    if (typeof pid === 'number')
+                        idx = pid;
+                    else if (typeof pid === 'string' && /^\d+$/.test(pid))
+                        idx = Number(pid);
+                    // If parentId is not an index, try to find by matching resourceId or id field
+                    if (idx !== null && elements[idx]) {
+                        cur = elements[idx];
+                        if (cur && (cur.clickable || cur.enabled || cur.focusable)) {
+                            resolvedAncestor = cur;
+                            break;
+                        }
+                    }
+                    else if (typeof pid === 'string') {
+                        // fallback: search elements for matching resourceId or id
+                        const found = elements.find((el) => (el.resourceId === pid || el.id === pid));
+                        if (found) {
+                            cur = found;
+                            if (cur && (cur.clickable || cur.enabled || cur.focusable)) {
+                                resolvedAncestor = cur;
+                                break;
+                            }
+                            // otherwise continue climbing if this found element has its own parentId
+                        }
+                        else {
+                            break;
+                        }
+                    }
+                    else {
+                        break;
+                    }
+                    safety++;
+                }
+            }
+            // Strategy 2: fallback - find a clickable element whose bounds fully contain the child's bounds
+            if (!resolvedAncestor && childBounds) {
+                const [cl, ct, cr, cb] = childBounds;
+                // find candidates that are clickable and contain the child bounds
+                const candidates = elements.filter((el) => el && (el.clickable || el.focusable) && Array.isArray(el.bounds) && el.bounds.length >= 4).map((el) => ({ el, bounds: el.bounds }));
+                let bestCandidate = null;
+                let bestCandidateArea = Infinity;
+                for (const c of candidates) {
+                    const [pl, pt, pr, pb] = c.bounds;
+                    if (pl <= cl && pt <= ct && pr >= cr && pb >= cb) {
+                        const area = (pr - pl) * (pb - pt);
+                        if (area < bestCandidateArea) {
+                            bestCandidateArea = area;
+                            bestCandidate = c.el;
+                        }
+                    }
+                }
+                if (bestCandidate)
+                    resolvedAncestor = bestCandidate;
+            }
+            if (resolvedAncestor) {
+                best = resolvedAncestor;
+                // small score bump to reflect actionability
+                bestScore = Math.min(1, bestScore + 0.02);
+            }
+        }
+        catch (e) {
+            console.error('Error resolving ancestor:', e);
+        }
+        if (!best)
+            return { found: false, error: 'Element not found' };
+        const boundsObj = Array.isArray(best.bounds) ? { left: best.bounds[0], top: best.bounds[1], right: best.bounds[2], bottom: best.bounds[3] } : null;
+        const tapCoordinates = boundsObj ? { x: Math.floor((boundsObj.left + boundsObj.right) / 2), y: Math.floor((boundsObj.top + boundsObj.bottom) / 2) } : null;
+        const outEl = {
+            text: best.text ?? null,
+            resourceId: best.resourceId ?? null,
+            contentDesc: best.contentDescription ?? best.contentDesc ?? null,
+            class: best.type ?? best.class ?? null,
+            bounds: boundsObj,
+            clickable: !!best.clickable,
+            enabled: !!best.enabled,
+            tapCoordinates,
+            telemetry: {
+                matchedIndex: best?._index ?? null,
+                matchedInteractable: !!best?._interactable
+            }
+        };
+        const scoreVal = Math.min(1, Number(bestScore.toFixed(3)));
+        return { found: true, element: outEl, score: scoreVal, confidence: scoreVal };
+    }
     static async waitForScreenChangeHandler({ platform, previousFingerprint, timeoutMs = 5000, pollIntervalMs = 300, deviceId }) {
         const start = Date.now();
         let lastFingerprint = null;
@@ -60,17 +246,180 @@ export class ToolsInteract {
                         lastFingerprint = confirmFp;
                         continue;
                     }
-                    catch {
-                        // ignore and continue polling
+                    catch (e) {
+                        console.error('Error confirming fingerprint:', e);
                         continue;
                     }
                 }
             }
-            catch {
-                // ignore transient errors
+            catch (e) {
+                console.error('Error getting screen fingerprint:', e);
             }
             await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
         }
         return { success: false, reason: 'timeout', lastFingerprint, elapsedMs: Date.now() - start };
     }
+    static async observeUntilHandler({ type, query, timeoutMs = 5000, pollIntervalMs = 200, platform, deviceId }) {
+        const start = Date.now();
+        const deadline = start + (timeoutMs || 0);
+        const q = (query === null || query === undefined) ? '' : String(query);
+        // Baseline state
+        let initialFingerprint = null;
+        try {
+            const fpRes = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId });
+            initialFingerprint = fpRes?.fingerprint ?? null;
+        }
+        catch (err) {
+            console.error('observeUntil: error getting initial fingerprint', err);
+            initialFingerprint = null;
+        }
+        // For logs, capture a baseline snapshot (count or last line) to avoid matching historical lines
+        let baselineLastLine = null;
+        try {
+            const gl = await ToolsObserve.getLogsHandler({ platform, deviceId, lines: 200 });
+            const logsArr = Array.isArray(gl.logs) ? gl.logs : [];
+            baselineLastLine = logsArr.length ? logsArr[logsArr.length - 1] : null;
+        }
+        catch (err) {
+            // non-fatal but surface warning to aid debugging
+            try {
+                console.warn('observeUntil: failed to get baseline logs (non-fatal):', err instanceof Error ? err.message : String(err));
+            }
+            catch { }
+        }
+        let lastChangeAt = Date.now();
+        let prevFingerprint = initialFingerprint;
+        const sleep = (ms) => new Promise(r => setTimeout(r, ms));
+        // Telemetry
+        let pollCount = 0;
+        let timeToMatch = null;
+        let matchSource = null;
+        while (Date.now() <= deadline) {
+            pollCount++;
+            try {
+                if (type === 'ui') {
+                    // fast findElement with short timeout to avoid blocking
+                    try {
+                        const found = await ToolsInteract.findElementHandler({ query: q, exact: false, timeoutMs: Math.min(500, timeoutMs || 500), platform, deviceId });
+                        if (found && found.found) {
+                            timeToMatch = Date.now() - start;
+                            // determine matchSource heuristics
+                            const el = found.element || {};
+                            if (el && el.resourceId && String(el.resourceId).toLowerCase().includes(q.toLowerCase()))
+                                matchSource = 'ui-resourceId';
+                            else if (el && el.text && String(el.text).toLowerCase() === q.toLowerCase())
+                                matchSource = 'ui-exact';
+                            else
+                                matchSource = 'ui-partial';
+                            return { success: true, type: 'ui', matched: true, details: `UI element matched '${q}'`, timestamp: Date.now(), element: found.element, telemetry: { pollCount, timeToMatch, elapsedMs: Date.now() - start, matchSource } };
+                        }
+                    }
+                    catch (err) {
+                        console.error('observeUntil(ui) find error:', err);
+                    }
+                }
+                else if (type === 'log') {
+                    try {
+                        // Try reading from active stream first
+                        const stream = await ToolsObserve.readLogStreamHandler({ platform, sessionId: 'default', limit: 200 });
+                        const entries = (stream && Array.isArray(stream.entries)) ? stream.entries : [];
+                        for (const ent of entries) {
+                            const msg = ent && (ent.message || ent.msg || ent) ? (ent.message || ent.msg || ent) : '';
+                            if (q && String(msg).includes(q)) {
+                                timeToMatch = Date.now() - start;
+                                matchSource = 'log-stream';
+                                return { success: true, type: 'log', matched: true, details: `Log matched '${q}'`, timestamp: Date.now(), log: { message: msg, raw: ent }, telemetry: { pollCount, timeToMatch, elapsedMs: Date.now() - start, matchSource } };
+                            }
+                        }
+                        // Fallback to snapshot logs
+                        const gl = await ToolsObserve.getLogsHandler({ platform, deviceId, lines: 200 });
+                        const logsArr = Array.isArray(gl && gl.logs) ? gl.logs : [];
+                        // Only consider new lines after baselineLastLine when possible
+                        let startIndex = 0;
+                        if (baselineLastLine) {
+                            const idx = logsArr.lastIndexOf(baselineLastLine);
+                            startIndex = idx >= 0 ? idx + 1 : 0;
+                        }
+                        for (let i = startIndex; i < logsArr.length; i++) {
+                            const line = logsArr[i];
+                            if (q && String(line).includes(q)) {
+                                timeToMatch = Date.now() - start;
+                                matchSource = 'log-snapshot';
+                                return { success: true, type: 'log', matched: true, details: `Log matched '${q}'`, timestamp: Date.now(), log: { message: line }, telemetry: { pollCount, timeToMatch, elapsedMs: Date.now() - start, matchSource } };
+                            }
+                        }
+                    }
+                    catch (err) {
+                        console.error('observeUntil(log) error:', err);
+                    }
+                }
+                else if (type === 'screen') {
+                    try {
+                        const fpRes = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId });
+                        const fp = fpRes?.fingerprint ?? null;
+                        if (fp !== null && fp !== undefined && fp !== initialFingerprint) {
+                            if (q) {
+                                // optionally validate query against new screen context
+                                try {
+                                    const found = await ToolsInteract.findElementHandler({ query: q, exact: false, timeoutMs: Math.min(500, timeoutMs || 500), platform, deviceId });
+                                    if (found && found.found) {
+                                        timeToMatch = Date.now() - start;
+                                        matchSource = 'screen-validated-ui';
+                                        return { success: true, type: 'screen', matched: true, details: `Screen changed and query matched on new screen`, timestamp: Date.now(), newFingerprint: fp, element: found.element, telemetry: { pollCount, timeToMatch, elapsedMs: Date.now() - start, matchSource } };
+                                    }
+                                }
+                                catch (err) {
+                                    console.error('observeUntil(screen) find error:', err);
+                                }
+                                // If query provided but not matched yet, continue polling until timeout
+                            }
+                            else {
+                                timeToMatch = Date.now() - start;
+                                matchSource = 'screen-fingerprint';
+                                return { success: true, type: 'screen', matched: true, details: 'Screen fingerprint changed', timestamp: Date.now(), newFingerprint: fp, telemetry: { pollCount, timeToMatch, elapsedMs: Date.now() - start, matchSource } };
+                            }
+                        }
+                    }
+                    catch (err) {
+                        console.error('observeUntil(screen) error:', err);
+                    }
+                }
+                else if (type === 'idle') {
+                    try {
+                        const fpRes = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId });
+                        const fp = fpRes?.fingerprint ?? null;
+                        if (fp !== prevFingerprint) {
+                            prevFingerprint = fp;
+                            lastChangeAt = Date.now();
+                        }
+                        else {
+                            if (Date.now() - lastChangeAt >= STABLE_IDLE_MS) {
+                                timeToMatch = Date.now() - start;
+                                matchSource = 'idle-stable';
+                                return { success: true, type: 'idle', matched: true, details: `UI stable for ${STABLE_IDLE_MS}ms`, timestamp: Date.now(), fingerprint: fp, telemetry: { pollCount, timeToMatch, elapsedMs: Date.now() - start, matchSource } };
+                            }
+                        }
+                    }
+                    catch (err) {
+                        console.error('observeUntil(idle) error:', err);
+                    }
+                }
+            }
+            catch (err) {
+                console.error('observeUntil: unexpected error', err);
+            }
+            // Respect poll interval and avoid tight loop
+            await sleep(pollIntervalMs || 200);
+        }
+        // On timeout, capture a failure snapshot to aid debugging (best-effort)
+        let snapshot = null;
+        try {
+            snapshot = await ToolsObserve.captureDebugSnapshotHandler({ reason: `observe_until timeout for ${type}`, includeLogs: true, platform, deviceId });
+        }
+        catch (err) {
+            snapshot = { error: err instanceof Error ? err.message : String(err) };
+        }
+        const elapsed = Date.now() - start;
+        return { success: false, error: 'Timeout waiting for condition', type, timeoutMs, telemetry: { pollCount, elapsedMs: elapsed, matchSource: null }, snapshot };
+    }
 }

package/dist/server.js

@@ -332,6 +332,21 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 required: ["platform", "text"]
             }
         },
+        {
+            name: "find_element",
+            description: "Find a UI element by semantic query (text, content-desc, resource-id, class). Returns best match.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    query: { type: "string", description: "Search query (text or label)" },
+                    exact: { type: "boolean", description: "Require exact match (true/false)", default: false },
+                    timeoutMs: { type: "number", description: "Timeout in ms to keep searching", default: 3000 },
+                    platform: { type: "string", enum: ["android", "ios"], description: "Optional platform override" },
+                    deviceId: { type: "string", description: "Optional device serial/udid" }
+                },
+                required: ["query"]
+            }
+        },
         {
             name: "tap",
             description: "Simulate a finger tap on the device screen at specific coordinates.",
@@ -602,6 +617,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const res = await ToolsInteract.waitForElementHandler({ platform, text, timeout, deviceId });
             return wrapResponse(res);
         }
+        if (name === "find_element") {
+            const { query, exact = false, timeoutMs = 3000, platform, deviceId } = (args || {});
+            const res = await ToolsInteract.findElementHandler({ query, exact, timeoutMs, platform, deviceId });
+            return wrapResponse(res);
+        }
         if (name === "tap") {
             const { platform, x, y, deviceId } = (args || {});
             const res = await ToolsInteract.tapHandler({ platform, x, y, deviceId });

package/docs/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to the **Mobile Debug MCP** project will be documented in this file.
 
+## [0.19.0]
+
+- Added `observe_until` interaction tool: waits for UI, log, screen fingerprint or idle conditions with configurable polling and timeout. Returns rich details on match (element info, log line, new fingerprint).
+
+
+## [0.18.0]
+- Added `find_element` interact tool: semantic UI element search with actionable tap coordinates and lightweight telemetry. The tool searches the UI tree for the best match by text, content description, resource-id, and class, scores candidates (exact, partial, resource-id), and returns the most relevant visible element. When a matching node is non-interactable (e.g., Compose Text child), the tool locates a clickable ancestor (parent or containing element) and returns actionable tapCoordinates (x,y). The handler also returns a `confidence` value and `telemetry` metadata (matchedIndex, matchedInteractable) to aid agent decision-making and logging. Implemented as `ToolsInteract.findElementHandler` and covered by unit tests.
+
+
 ## [0.17.0]
 - Added `capture_debug_snapshot` observe tool: captures a full debugging snapshot including screenshot (base64), UI tree, current activity (Android), screen fingerprint, and recent logs (prefers active log stream, falls back to snapshot logs). Returns a single structured JSON object and includes per-part error fields for partial failures. Implemented as `ToolsObserve.captureDebugSnapshotHandler` and registered in the server.
 

package/docs/tools/interact.md

@@ -101,3 +101,105 @@ Notes:
 - 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`).
 
+---
+
+## find_element
+
+Purpose:
+
+Locate a UI element on the current screen using semantic matching and return an actionable element descriptor (including tap coordinates) and confidence telemetry.
+
+Input:
+
+```json
+{ "query": "string", "exact": false, "timeoutMs": 3000, "platform": "android|ios", "deviceId": "optional device id" }
+```
+
+Behaviour:
+
+- Fetches the current UI tree (get_ui_tree) and scores visible elements using: text, content description, resource-id, and class name.
+- Normalises strings (lowercase, trimmed). If exact=true require exact match; otherwise allow partial matches (contains) and resource-id/class matches.
+- Considers element bounds and visibility; scores non-interactable children as matches and attempts to resolve a clickable ancestor (parent index or containing clickable element) to produce an actionable element.
+- Retries until timeoutMs; stops early for high-confidence matches.
+- Does not block on long operations and returns partial results where appropriate.
+
+Output:
+
+```json
+{
+  "found": true,
+  "element": {
+    "text": "Login",
+    "resourceId": "com.example:id/login",
+    "contentDesc": null,
+    "class": "android.widget.Button",
+    "bounds": { "left":0, "top":0, "right":100, "bottom":50 },
+    "clickable": true,
+    "enabled": true,
+    "tapCoordinates": { "x":50, "y":25 },
+    "telemetry": { "matchedIndex": 3, "matchedInteractable": true }
+  },
+  "score": 1.0,
+  "confidence": 1.0
+}
+```
+
+Notes:
+
+- `tapCoordinates` are the recommended center point to use for `tap` calls.
+- `confidence` mirrors the internal scoring (0..1) and is suitable for telemetry or logging to decide whether to proceed with an automated action.
+- The tool favours actionable (clickable/focusable) targets; when a matching node is not directly actionable, it finds the smallest containing clickable ancestor.
+- Unit tests for edge cases (parent-clickable child-text, resource-id matches, fuzzy matching) are under `test/observe/unit/find_element.test.ts`.
+
+---
+
+## observe_until
+
+Purpose:
+- Wait for a condition to occur on the device: UI element appearance, a log line, a screen fingerprint change, or an idle/stable screen state.
+
+Supported types and behavior:
+- ui: Delegates to `find_element` to perform a semantic search of the UI tree. Returns the matched element descriptor (including tapCoordinates) when found.
+- log: Reads the active log stream (via `start_log_stream`/`readLogStreamHandler`) and falls back to a snapshot of recent logs (`getLogsHandler`). Matches when the query substring appears in a new log line after a captured baseline.
+- screen: Compares screen fingerprints (visual checks) against an initial baseline and returns when fingerprint changes. If `query` is provided it will attempt a `find_element` on the new screen to validate the expected content.
+- idle: Waits until the screen fingerprint remains stable for a short stability window (default 1000ms).
+
+Input (ToolsInteract.observeUntilHandler):
+```
+{ "type": "ui|log|screen|idle", "query": "optional string", "timeoutMs": 5000, "pollIntervalMs": 200, "platform": "android|ios", "deviceId": "optional device id" }
+```
+
+Success response highlights:
+- success: true
+- type: requested type
+- matched: true
+- details: human-friendly explanation
+- timestamp: epoch ms
+- element: (for ui/screen when matched) actionable element metadata with tapCoordinates
+- log: (for log) matched log message and raw entry
+- newFingerprint: (for screen) new fingerprint value
+
+Failure/timeout response:
+- success: false
+- error or reason: explanation
+- type: requested type
+- timeoutMs: value used
+
+Notes & tips:
+- Defaults (timeoutMs=5000, pollIntervalMs=200) balance responsiveness with device query overhead; adjust in tests or scripts as needed.
+- For UI-sensitive flows prefer type='ui' rather than relying solely on visual fingerprint changes, as some UI updates don't alter the fingerprint.
+
+Tests:
+- Unit: `test/interact/unit/observe_until.test.ts`
+- Device runner: `test/interact/device/observe_until_device.ts` (requires devices/emulators and adb/xcrun in PATH)
+
+Example:
+```
+// Wait up to 5s for a button labeled "Generate Session" on Android
+ToolsInteract.observeUntilHandler({ type: 'ui', query: 'Generate Session', timeoutMs: 5000, platform: 'android' })
+```
+
+Troubleshooting:
+- If observe_until(log) never matches, ensure log streaming is started for the target package and baseline logs captured correctly.
+- If observe_until(screen) times out despite visible UI change, try type='ui' to validate content-level changes.
+

package/package.json

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

package/src/interact/index.ts

@@ -7,6 +7,30 @@ import { ToolsObserve } from '../observe/index.js'
 
 interface ScreenFingerprintResponse { fingerprint: string | null }
 
+interface UiElement {
+  text?: string | null
+  label?: string | null
+  value?: string | null
+  contentDescription?: string | null
+  contentDesc?: string | null
+  accessibilityLabel?: string | null
+  resourceId?: string | null
+  resourceID?: string | null
+  id?: string | null
+  type?: string | null
+  class?: string | null
+  bounds?: number[] | null
+  clickable?: boolean
+  enabled?: boolean
+  focusable?: boolean
+  visible?: boolean
+  parentId?: number | string | null
+  _index?: number
+  _interactable?: boolean
+}
+
+const STABLE_IDLE_MS = 1000
+
 export class ToolsInteract {
 
   private static async getInteractionService(platform?: 'android' | 'ios', deviceId?: string) {
@@ -47,6 +71,160 @@ export class ToolsInteract {
     return await interact.scrollToElement(selector, direction, maxScrolls, scrollAmount, resolved.id)
   }
 
+  static async findElementHandler({ query, exact = false, timeoutMs = 3000, platform, deviceId }: { query: string, exact?: boolean, timeoutMs?: number, platform?: 'android' | 'ios', deviceId?: string }) {
+    // Try to use observe layer to fetch the current UI tree and perform a fast semantic search
+    const start = Date.now()
+    const deadline = start + timeoutMs
+    const normalize = (s: any) => (s === null || s === undefined) ? '' : String(s).toLowerCase().trim()
+
+    const q = normalize(query)
+    if (!q) return { found: false, error: 'Empty query' }
+
+    let best: UiElement | null = null
+    let bestScore = 0
+
+    const scoreElement = (el: UiElement | null) => {
+      if (!el || !el.visible) return 0
+      const bounds = el.bounds || [0,0,0,0]
+      if (!Array.isArray(bounds) || bounds.length < 4) return 0
+      const [l,t,r,b] = bounds
+      if (r <= l || b <= t) return 0
+      // Do not early-return on non-interactable elements — score them so we can locate their clickable ancestor later
+      const interactable = !!(el.clickable || el.enabled || el.focusable)
+
+      const text = normalize(el.text ?? el.label ?? el.value ?? '')
+      const content = normalize(el.contentDescription ?? el.contentDesc ?? el.accessibilityLabel ?? '')
+      const resourceId = normalize(el.resourceId ?? el.resourceID ?? el.id ?? '')
+      const className = normalize(el.type ?? el.class ?? '')
+
+      let score = 0
+      if (exact) {
+        if (text && text === q) score = 1.0
+        else if (content && content === q) score = 0.95
+      } else {
+        if (text && text === q) score = 1.0
+        else if (content && content === q) score = 0.95
+        else if (text && text.includes(q)) score = 0.6
+        else if (content && content.includes(q)) score = 0.55
+        else if (resourceId && resourceId.includes(q)) score = 0.7
+        else if (className && className.includes(q)) score = 0.3
+      }
+      if (score > 0 && interactable) score += 0.05
+      return score
+    }
+
+    while (Date.now() <= deadline) {
+      try {
+        const tree = await ToolsObserve.getUITreeHandler({ platform, deviceId })
+        if (tree && Array.isArray((tree as any).elements)) {
+          const elements = ((tree as any).elements as UiElement[])
+          for (let i = 0; i < elements.length; i++) {
+            const el = elements[i]
+            try {
+              const s = scoreElement(el)
+              const interactable = !!(el.clickable || el.enabled || (el as any).focusable)
+              if (s > bestScore) {
+                bestScore = s
+                best = el as UiElement
+                if (best) { best._index = i; best._interactable = interactable }
+              }
+              if (bestScore >= 0.95) break
+            } catch (e) { console.error('Error scoring element:', e) }
+          }
+          if (bestScore >= 0.95) break
+        }
+      } catch (e) { console.error('Error fetching UI tree:', e) }
+      if (Date.now() > deadline) break
+      await new Promise(r => setTimeout(r, 100))
+    }
+
+    if (!best) return { found: false, error: 'Element not found' }
+
+    // If the best match is not interactable, try to resolve an actionable ancestor.
+    try {
+      const tree = await ToolsObserve.getUITreeHandler({ platform, deviceId }) as any
+      const elements = (tree && Array.isArray(tree.elements)) ? (tree.elements as UiElement[]) : []
+      let chosen = best as any
+      const childBounds = Array.isArray(chosen?.bounds) ? chosen.bounds : null
+
+      // Strategy 1: if parentId references an index, climb that chain
+      let resolvedAncestor: any = null
+      if (childBounds && (chosen.parentId !== undefined && chosen.parentId !== null)) {
+        let cur = chosen
+        let safety = 0
+        while (cur && safety < 20 && !(cur.clickable || cur.focusable) && (cur.parentId !== undefined && cur.parentId !== null)) {
+          let pid = cur.parentId
+          let idx: number | null = null
+          if (typeof pid === 'number') idx = pid
+          else if (typeof pid === 'string' && /^\d+$/.test(pid)) idx = Number(pid)
+          // If parentId is not an index, try to find by matching resourceId or id field
+          if (idx !== null && elements[idx]) {
+            cur = elements[idx]
+            if (cur && (cur.clickable || cur.enabled || cur.focusable)) { resolvedAncestor = cur; break }
+          } else if (typeof pid === 'string') {
+            // fallback: search elements for matching resourceId or id
+            const found = elements.find((el: UiElement)=> (el.resourceId === pid || el.id === pid))
+            if (found) {
+              cur = found
+              if (cur && (cur.clickable || cur.enabled || cur.focusable)) { resolvedAncestor = cur; break }
+              // otherwise continue climbing if this found element has its own parentId
+            } else {
+              break
+            }
+          } else {
+            break
+          }
+          safety++
+        }
+      }
+
+      // Strategy 2: fallback - find a clickable element whose bounds fully contain the child's bounds
+      if (!resolvedAncestor && childBounds) {
+        const [cl,ct,cr,cb] = childBounds
+        // find candidates that are clickable and contain the child bounds
+        const candidates = elements.filter((el: UiElement)=> el && (el.clickable || el.focusable) && Array.isArray(el.bounds) && el.bounds!.length>=4).map((el: UiElement)=>({el, bounds: el.bounds! as number[]}))
+        let bestCandidate: any = null
+        let bestCandidateArea = Infinity
+        for (const c of candidates) {
+          const [pl,pt,pr,pb] = c.bounds
+          if (pl <= cl && pt <= ct && pr >= cr && pb >= cb) {
+            const area = (pr-pl) * (pb-pt)
+            if (area < bestCandidateArea) { bestCandidateArea = area; bestCandidate = c.el }
+          }
+        }
+        if (bestCandidate) resolvedAncestor = bestCandidate
+      }
+
+      if (resolvedAncestor) {
+        best = resolvedAncestor
+        // small score bump to reflect actionability
+        bestScore = Math.min(1, bestScore + 0.02)
+      }
+    } catch (e) { console.error('Error resolving ancestor:', e) }
+
+    if (!best) return { found: false, error: 'Element not found' }
+
+    const boundsObj = Array.isArray(best.bounds) ? { left: best.bounds[0], top: best.bounds[1], right: best.bounds[2], bottom: best.bounds[3] } : null
+    const tapCoordinates = boundsObj ? { x: Math.floor((boundsObj.left + boundsObj.right) / 2), y: Math.floor((boundsObj.top + boundsObj.bottom) / 2) } : null
+
+    const outEl = {
+      text: best.text ?? null,
+      resourceId: best.resourceId ?? null,
+      contentDesc: best.contentDescription ?? best.contentDesc ?? null,
+      class: best.type ?? best.class ?? null,
+      bounds: boundsObj,
+      clickable: !!best.clickable,
+      enabled: !!best.enabled,
+      tapCoordinates,
+      telemetry: {
+        matchedIndex: best?._index ?? null,
+        matchedInteractable: !!best?._interactable
+      }
+    }
+    const scoreVal = Math.min(1, Number(bestScore.toFixed(3)))
+    return { found: true, element: outEl, score: scoreVal, confidence: scoreVal }
+  }
+
   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
@@ -74,14 +252,9 @@ export class ToolsInteract {
             }
             lastFingerprint = confirmFp
             continue
-          } catch {
-            // ignore and continue polling
-            continue
-          }
+          } catch (e) { console.error('Error confirming fingerprint:', e); continue }
         }
-      } catch {
-        // ignore transient errors
-      }
+      } catch (e) { console.error('Error getting screen fingerprint:', e) }
 
       await new Promise(resolve => setTimeout(resolve, pollIntervalMs))
     }
@@ -89,4 +262,147 @@ export class ToolsInteract {
     return { success: false, reason: 'timeout', lastFingerprint, elapsedMs: Date.now() - start }
   }
 
+  static async observeUntilHandler({ type, query, timeoutMs = 5000, pollIntervalMs = 200, platform, deviceId }: { type: 'ui' | 'log' | 'screen' | 'idle', query?: string, timeoutMs?: number, pollIntervalMs?: number, platform?: 'android' | 'ios', deviceId?: string }) {
+    const start = Date.now()
+    const deadline = start + (timeoutMs || 0)
+    const q = (query === null || query === undefined) ? '' : String(query)
+
+    // Baseline state
+    let initialFingerprint: string | null = null
+    try {
+      const fpRes = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId }) as ScreenFingerprintResponse | null
+      initialFingerprint = fpRes?.fingerprint ?? null
+    } catch (err) { console.error('observeUntil: error getting initial fingerprint', err); initialFingerprint = null }
+
+    // For logs, capture a baseline snapshot (count or last line) to avoid matching historical lines
+    let baselineLastLine: string | null = null
+    try {
+      const gl = await ToolsObserve.getLogsHandler({ platform, deviceId, lines: 200 })
+      const logsArr = Array.isArray((gl as any).logs) ? (gl as any).logs : []
+      baselineLastLine = logsArr.length ? logsArr[logsArr.length - 1] : null
+    } catch (err) {
+      // non-fatal but surface warning to aid debugging
+      try { console.warn('observeUntil: failed to get baseline logs (non-fatal):', err instanceof Error ? err.message : String(err)) } catch { }
+    }
+
+    
+    let lastChangeAt = Date.now()
+    let prevFingerprint = initialFingerprint
+
+    const sleep = (ms: number) => new Promise(r => setTimeout(r, ms))
+
+    // Telemetry
+    let pollCount = 0
+    let timeToMatch: number | null = null
+    let matchSource: string | null = null
+
+    while (Date.now() <= deadline) {
+      pollCount++
+      try {
+        if (type === 'ui') {
+          // fast findElement with short timeout to avoid blocking
+          try {
+            const found = await ToolsInteract.findElementHandler({ query: q, exact: false, timeoutMs: Math.min(500, timeoutMs || 500), platform, deviceId })
+            if (found && (found as any).found) {
+              timeToMatch = Date.now() - start
+              // determine matchSource heuristics
+              const el = (found as any).element || {}
+              if (el && el.resourceId && String(el.resourceId).toLowerCase().includes(q.toLowerCase())) matchSource = 'ui-resourceId'
+              else if (el && el.text && String(el.text).toLowerCase() === q.toLowerCase()) matchSource = 'ui-exact'
+              else matchSource = 'ui-partial'
+
+              return { success: true, type: 'ui', matched: true, details: `UI element matched '${q}'`, timestamp: Date.now(), element: (found as any).element, telemetry: { pollCount, timeToMatch, elapsedMs: Date.now() - start, matchSource } }
+            }
+          } catch (err) { console.error('observeUntil(ui) find error:', err) }
+        } else if (type === 'log') {
+          try {
+            // Try reading from active stream first
+            const stream = await ToolsObserve.readLogStreamHandler({ platform, sessionId: 'default', limit: 200 }) as any
+            const entries = (stream && Array.isArray(stream.entries)) ? stream.entries : []
+            for (const ent of entries) {
+              const msg = ent && (ent.message || ent.msg || ent) ? (ent.message || ent.msg || ent) : ''
+              if (q && String(msg).includes(q)) {
+                timeToMatch = Date.now() - start
+                matchSource = 'log-stream'
+                return { success: true, type: 'log', matched: true, details: `Log matched '${q}'`, timestamp: Date.now(), log: { message: msg, raw: ent }, telemetry: { pollCount, timeToMatch, elapsedMs: Date.now() - start, matchSource } }
+              }
+            }
+
+            // Fallback to snapshot logs
+            const gl = await ToolsObserve.getLogsHandler({ platform, deviceId, lines: 200 }) as any
+            const logsArr = Array.isArray(gl && gl.logs) ? gl.logs : []
+            // Only consider new lines after baselineLastLine when possible
+            let startIndex = 0
+            if (baselineLastLine) {
+              const idx = logsArr.lastIndexOf(baselineLastLine)
+              startIndex = idx >= 0 ? idx + 1 : 0
+            }
+            for (let i = startIndex; i < logsArr.length; i++) {
+              const line = logsArr[i]
+              if (q && String(line).includes(q)) {
+                timeToMatch = Date.now() - start
+                matchSource = 'log-snapshot'
+                return { success: true, type: 'log', matched: true, details: `Log matched '${q}'`, timestamp: Date.now(), log: { message: line }, telemetry: { pollCount, timeToMatch, elapsedMs: Date.now() - start, matchSource } }
+              }
+            }
+          } catch (err) { console.error('observeUntil(log) error:', err) }
+        } else if (type === 'screen') {
+          try {
+            const fpRes = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId }) as ScreenFingerprintResponse | null
+            const fp = fpRes?.fingerprint ?? null
+            if (fp !== null && fp !== undefined && fp !== initialFingerprint) {
+              if (q) {
+                // optionally validate query against new screen context
+                try {
+                  const found = await ToolsInteract.findElementHandler({ query: q, exact: false, timeoutMs: Math.min(500, timeoutMs || 500), platform, deviceId })
+                  if (found && (found as any).found) {
+                    timeToMatch = Date.now() - start
+                    matchSource = 'screen-validated-ui'
+                    return { success: true, type: 'screen', matched: true, details: `Screen changed and query matched on new screen`, timestamp: Date.now(), newFingerprint: fp, element: (found as any).element, telemetry: { pollCount, timeToMatch, elapsedMs: Date.now() - start, matchSource } }
+                  }
+                } catch (err) { console.error('observeUntil(screen) find error:', err) }
+                // If query provided but not matched yet, continue polling until timeout
+              } else {
+                timeToMatch = Date.now() - start
+                matchSource = 'screen-fingerprint'
+                return { success: true, type: 'screen', matched: true, details: 'Screen fingerprint changed', timestamp: Date.now(), newFingerprint: fp, telemetry: { pollCount, timeToMatch, elapsedMs: Date.now() - start, matchSource } }
+              }
+            }
+          } catch (err) { console.error('observeUntil(screen) error:', err) }
+        } else if (type === 'idle') {
+          try {
+            const fpRes = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId }) as ScreenFingerprintResponse | null
+            const fp = fpRes?.fingerprint ?? null
+            if (fp !== prevFingerprint) {
+              prevFingerprint = fp
+              lastChangeAt = Date.now()
+            } else {
+              if (Date.now() - lastChangeAt >= STABLE_IDLE_MS) {
+                timeToMatch = Date.now() - start
+                matchSource = 'idle-stable'
+                return { success: true, type: 'idle', matched: true, details: `UI stable for ${STABLE_IDLE_MS}ms`, timestamp: Date.now(), fingerprint: fp, telemetry: { pollCount, timeToMatch, elapsedMs: Date.now() - start, matchSource } }
+              }
+            }
+          } catch (err) { console.error('observeUntil(idle) error:', err) }
+        }
+      } catch (err) {
+        console.error('observeUntil: unexpected error', err)
+      }
+
+      // Respect poll interval and avoid tight loop
+      await sleep(pollIntervalMs || 200)
+    }
+
+    // On timeout, capture a failure snapshot to aid debugging (best-effort)
+    let snapshot: any = null
+    try {
+      snapshot = await ToolsObserve.captureDebugSnapshotHandler({ reason: `observe_until timeout for ${type}`, includeLogs: true, platform, deviceId })
+    } catch (err) {
+      snapshot = { error: err instanceof Error ? err.message : String(err) }
+    }
+
+    const elapsed = Date.now() - start
+    return { success: false, error: 'Timeout waiting for condition', type, timeoutMs, telemetry: { pollCount, elapsedMs: elapsed, matchSource: null }, snapshot }
+  }
+
 }

package/src/server.ts

@@ -354,6 +354,21 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         required: ["platform", "text"]
       }
     },
+    {
+      name: "find_element",
+      description: "Find a UI element by semantic query (text, content-desc, resource-id, class). Returns best match.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          query: { type: "string", description: "Search query (text or label)" },
+          exact: { type: "boolean", description: "Require exact match (true/false)", default: false },
+          timeoutMs: { type: "number", description: "Timeout in ms to keep searching", default: 3000 },
+          platform: { type: "string", enum: ["android","ios"], description: "Optional platform override" },
+          deviceId: { type: "string", description: "Optional device serial/udid" }
+        },
+        required: ["query"]
+      }
+    },
 
     {
       name: "tap",
@@ -647,6 +662,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       return wrapResponse(res)
     }
 
+    if (name === "find_element") {
+      const { query, exact = false, timeoutMs = 3000, platform, deviceId } = (args || {}) as any
+      const res = await ToolsInteract.findElementHandler({ query, exact, timeoutMs, platform, deviceId })
+      return wrapResponse(res)
+    }
+
     if (name === "tap") {
       const { platform, x, y, deviceId } = (args || {}) as any
       const res = await ToolsInteract.tapHandler({ platform, x, y, deviceId })

package/test/interact/device/observe_until_device.ts

@@ -0,0 +1,24 @@
+(async function main(){
+  try{
+    const inter = await import('../../src/interact/index.ts')
+    const manage = await import('../../src/manage/index.ts')
+    const ToolsInteract = (inter as any).ToolsInteract
+    const ToolsManage = (manage as any).ToolsManage
+
+    const ANDROID_ID = process.env.ANDROID_DEVICE || 'emulator-5554'
+    const IOS_UDID = process.env.IOS_DEVICE || '2EFFD8FD-5D09-47CC-95F8-28BBE30AF7ED'
+    console.log('Device test starting. Android:', ANDROID_ID, 'iOS:', IOS_UDID)
+
+    // Start modul8 on both platforms if present
+    try { await ToolsManage.startAppHandler({ platform: 'android', appId: 'com.ideamechanics.modul8', deviceId: ANDROID_ID }); console.log('Started android app (if installed)') } catch(e){ console.error('Android start skipped:', e.message || e) }
+    try { await ToolsManage.startAppHandler({ platform: 'ios', appId: 'com.ideamechanics.modul8.Modul8', deviceId: IOS_UDID }); console.log('Started ios app (if installed)') } catch(e){ console.error('iOS start skipped:', e.message || e) }
+
+    // Observe UI for Generate Session on both devices (will timeout if not present)
+    const aRes = await ToolsInteract.observeUntilHandler({ type: 'ui', query: 'Generate Session', timeoutMs: 20000, pollIntervalMs: 500, platform: 'android', deviceId: ANDROID_ID })
+    console.log('Android observe result:', JSON.stringify(aRes, null, 2))
+
+    const iRes = await ToolsInteract.observeUntilHandler({ type: 'ui', query: 'Generate Session', timeoutMs: 20000, pollIntervalMs: 500, platform: 'ios', deviceId: IOS_UDID })
+    console.log('iOS observe result:', JSON.stringify(iRes, null, 2))
+
+  } catch (e) { console.error('ERR', e); process.exit(1) }
+})()

package/test/interact/unit/observe_until.test.ts

@@ -0,0 +1,76 @@
+import { ToolsInteract } from '../../../src/interact/index.js'
+import * as Observe from '../../../src/observe/index.js'
+
+async function runTests() {
+  console.log('Starting observe_until unit tests...')
+
+  const origFind = (ToolsInteract as any).findElementHandler
+  const origReadLog = (Observe as any).ToolsObserve.readLogStreamHandler
+  const origGetLogs = (Observe as any).ToolsObserve.getLogsHandler
+  const origGetFp = (Observe as any).ToolsObserve.getScreenFingerprintHandler
+  const origResolveObserve = (Observe as any).ToolsObserve.resolveObserve
+  const origGetScreenFp = (Observe as any).ToolsObserve.getScreenFingerprintHandler
+
+  try {
+    // Timeout / snapshot case: ensure snapshot captured when condition not met
+    const origCapture = (Observe as any).ToolsObserve.captureDebugSnapshotHandler
+    ;(Observe as any).ToolsObserve.captureDebugSnapshotHandler = async ({ reason }: any) => ({ reason, fingerprint: 'snap-123', ui_tree: null, logs: [] })
+    // make findElement always fail
+    (ToolsInteract as any).findElementHandler = async () => ({ found: false })
+    const resTimeout = await ToolsInteract.observeUntilHandler({ type: 'ui', query: 'WillNeverExist', timeoutMs: 500, pollIntervalMs: 100, platform: 'android' })
+    const okTimeout = resTimeout && !(resTimeout as any).success && (resTimeout as any).snapshot && (resTimeout as any).snapshot.fingerprint === 'snap-123' && (resTimeout as any).telemetry && (resTimeout as any).telemetry.pollCount > 0
+    console.log('Timeout Snapshot Test:', okTimeout ? 'PASS' : 'FAIL', JSON.stringify((resTimeout as any).telemetry || {}, null, 2))
+    ;(Observe as any).ToolsObserve.captureDebugSnapshotHandler = origCapture
+
+    // UI condition: findElement returns found on 2nd call
+    let calls = 0
+    ;(ToolsInteract as any).findElementHandler = async (args) => {
+      calls++
+      const query = (args && (args.query || args)) || ''
+      if (calls >= 2) return { found: true, element: { text: query } }
+      return { found: false }
+    }
+
+    const resUi = await ToolsInteract.observeUntilHandler({ type: 'ui', query: 'Generate Session', timeoutMs: 3000, pollIntervalMs: 100, platform: 'android' })
+    const okUi = resUi && (resUi as any).success && (resUi as any).telemetry && (resUi as any).telemetry.pollCount > 0 && (resUi as any).telemetry.timeToMatch >= 0
+    console.log('UI Test:', okUi ? 'PASS' : 'FAIL', JSON.stringify((resUi as any).telemetry || {}, null, 2))
+
+    // Log condition: stream empty, snapshot contains matching line
+    ;(Observe as any).ToolsObserve.readLogStreamHandler = async () => ({ entries: [ { message: 'nothing' } ] })
+    let glCalls = 0
+    ;(Observe as any).ToolsObserve.getLogsHandler = async () => {
+      glCalls++
+      if (glCalls === 1) return { device: {}, logs: ['INFO start'] }
+      return { device: {}, logs: ['INFO start', 'ERROR Exception occurred', 'Server: Boom'] }
+    }
+
+    const resLog = await ToolsInteract.observeUntilHandler({ type: 'log', query: 'Server', timeoutMs: 3000, pollIntervalMs: 100, platform: 'android' })
+    const okLog = resLog && (resLog as any).success && (resLog as any).telemetry && (resLog as any).telemetry.pollCount > 0 && (resLog as any).telemetry.matchSource === 'log-snapshot'
+    console.log('Log Test:', okLog ? 'PASS' : 'FAIL', JSON.stringify((resLog as any).telemetry || {}, null, 2))
+
+    // Screen condition: fingerprint changes after a few polls
+    let seq = ['A', 'A', 'B']
+    ;(Observe as any).ToolsObserve.getScreenFingerprintHandler = async () => ({ fingerprint: seq.length ? seq.shift() : null })
+    const resScreen = await ToolsInteract.observeUntilHandler({ type: 'screen', timeoutMs: 3000, pollIntervalMs: 100, platform: 'android' })
+    const okScreen = resScreen && (resScreen as any).success && (resScreen as any).telemetry && (resScreen as any).telemetry.matchSource === 'screen-fingerprint'
+    console.log('Screen Test:', okScreen ? 'PASS' : 'FAIL', JSON.stringify((resScreen as any).telemetry || {}, null, 2))
+
+    // Idle condition: stable fingerprints observed
+    let idleSeq = ['X', 'X', 'X']
+    ;(Observe as any).ToolsObserve.getScreenFingerprintHandler = async () => ({ fingerprint: idleSeq.length ? idleSeq.shift() : 'X' })
+    const resIdle = await ToolsInteract.observeUntilHandler({ type: 'idle', timeoutMs: 3000, pollIntervalMs: 100, platform: 'android' })
+    const okIdle = resIdle && (resIdle as any).success && (resIdle as any).telemetry && (resIdle as any).telemetry.matchSource === 'idle-stable'
+    console.log('Idle Test:', okIdle ? 'PASS' : 'FAIL', JSON.stringify((resIdle as any).telemetry || {}, null, 2))
+
+  } finally {
+    ;(ToolsInteract as any).findElementHandler = origFind
+    ;(Observe as any).ToolsObserve.readLogStreamHandler = origReadLog
+    ;(Observe as any).ToolsObserve.getLogsHandler = origGetLogs
+    ;(Observe as any).ToolsObserve.getScreenFingerprintHandler = origGetFp
+    ;(Observe as any).ToolsObserve.resolveObserve = origResolveObserve
+    ;(Observe as any).ToolsObserve.getScreenFingerprintHandler = origGetScreenFp
+    ;(Observe as any).ToolsObserve.getScreenFingerprintHandler = origGetScreenFp
+  }
+}
+
+runTests().catch(console.error)

package/test/observe/unit/find_element.test.ts

@@ -0,0 +1,85 @@
+import { ToolsInteract } from '../../../src/interact/index.js'
+import { ToolsObserve } from '../../../src/observe/index.js'
+
+async function run() {
+  process.stdout.write('Starting find_element unit tests...\n')
+
+  const origGetTree = (ToolsObserve as any).getUITreeHandler
+
+  try {
+    // Test 1: exact text match
+    (ToolsObserve as any).getUITreeHandler = async () => ({
+      device: { platform: 'android', id: 'mock' },
+      screen: '',
+      resolution: { width: 1080, height: 1920 },
+      elements: [
+        { text: 'Login', type: 'android.widget.Button', contentDescription: null, clickable: true, enabled: true, visible: true, bounds: [10,10,100,60], resourceId: 'btn_login' },
+        { text: 'Cancel', type: 'android.widget.Button', contentDescription: null, clickable: true, enabled: true, visible: true, bounds: [110,10,200,60], resourceId: 'btn_cancel' }
+      ]
+    })
+
+    const res1: any = await ToolsInteract.findElementHandler({ query: 'login', exact: true, platform: 'android' })
+    process.stdout.write('res1 ' + JSON.stringify(res1, null, 2) + '\n');
+    const pass1 = res1.found === true && res1.element && res1.element.resourceId === 'btn_login' && res1.element.tapCoordinates && typeof res1.element.tapCoordinates.x === 'number' && typeof res1.element.tapCoordinates.y === 'number' && typeof res1.confidence === 'number'
+    process.stdout.write('Test 1: ' + (pass1 ? 'PASS' : 'FAIL') + '\n');
+
+    // Test 2: partial match & scoring
+    (ToolsObserve as any).getUITreeHandler = async () => ({
+      device: { platform: 'android', id: 'mock' },
+      screen: '',
+      resolution: { width: 1080, height: 1920 },
+      elements: [
+        { text: 'Sign in', type: 'android.widget.Button', contentDescription: null, clickable: true, enabled: true, visible: true, bounds: [10,10,100,60], resourceId: 'btn_signin' },
+        { text: 'Login with Email', type: 'android.widget.Button', contentDescription: null, clickable: true, enabled: true, visible: true, bounds: [110,10,300,60], resourceId: 'btn_login_email' }
+      ]
+    })
+
+    const res2: any = await ToolsInteract.findElementHandler({ query: 'login', exact: false, platform: 'android' })
+    process.stdout.write('res2 ' + JSON.stringify(res2, null, 2) + '\n');
+    const pass2 = res2.found === true && res2.element && res2.element.resourceId === 'btn_login_email' && res2.element.tapCoordinates && typeof res2.element.tapCoordinates.x === 'number' && typeof res2.element.tapCoordinates.y === 'number' && typeof res2.confidence === 'number'
+    process.stdout.write('Test 2: ' + (pass2 ? 'PASS' : 'FAIL') + '\n');
+
+    // Test 3: resourceId match
+    (ToolsObserve as any).getUITreeHandler = async () => ({
+      device: { platform: 'android', id: 'mock' },
+      screen: '',
+      resolution: { width: 1080, height: 1920 },
+      elements: [
+        { text: null, type: 'android.widget.ImageView', contentDescription: null, clickable: false, enabled: true, visible: true, bounds: [0,0,50,50], resourceId: 'icon_login' }
+      ]
+    })
+
+    const res3: any = await ToolsInteract.findElementHandler({ query: 'icon_login', exact: false, platform: 'android' })
+    process.stdout.write('res3 ' + JSON.stringify(res3, null, 2) + '\n');
+    const pass3 = res3.found === true && res3.element && res3.element.resourceId === 'icon_login' && res3.element.tapCoordinates && typeof res3.element.tapCoordinates.x === 'number' && typeof res3.element.tapCoordinates.y === 'number' && typeof res3.confidence === 'number'
+    process.stdout.write('Test 3: ' + (pass3 ? 'PASS' : 'FAIL') + '\n');
+
+    // Test 4: parent-clickable child-text scenario
+    (ToolsObserve as any).getUITreeHandler = async () => ({
+      device: { platform: 'android', id: 'mock' },
+      screen: '',
+      resolution: { width: 1080, height: 1920 },
+      elements: [
+        { text: null, type: 'android.view.View', contentDescription: null, clickable: true, enabled: true, visible: true, bounds: [0,0,400,100], resourceId: 'btn_generate', children: [1] },
+        { text: 'Generate Session', type: 'android.widget.TextView', contentDescription: null, clickable: false, enabled: true, visible: true, bounds: [10,10,390,90], resourceId: null, parentId: 0 }
+      ]
+    })
+
+    const res4: any = await ToolsInteract.findElementHandler({ query: 'generate', exact: false, platform: 'android', timeoutMs: 300 })
+    process.stdout.write('res4 ' + JSON.stringify(res4, null, 2) + '\n');
+    const pass4 = res4.found === true && res4.element && res4.element.clickable === true && res4.element.resourceId === 'btn_generate' && res4.element.tapCoordinates && typeof res4.element.tapCoordinates.x === 'number' && typeof res4.element.tapCoordinates.y === 'number' && typeof res4.confidence === 'number'
+    process.stdout.write('Test 4: ' + (pass4 ? 'PASS' : 'FAIL') + '\n');
+
+    // Test 5: not found
+    (ToolsObserve as any).getUITreeHandler = async () => ({ device: { platform: 'android', id: 'mock' }, screen: '', resolution: { width: 1080, height: 1920 }, elements: [] })
+    const res5: any = await ToolsInteract.findElementHandler({ query: 'nope', exact: false, platform: 'android', timeoutMs: 300 })
+    process.stdout.write('res5 ' + JSON.stringify(res5, null, 2) + '\n');
+    const pass5 = res5.found === false
+    process.stdout.write('Test 5: ' + (pass5 ? 'PASS' : 'FAIL') + '\n');
+
+  } finally {
+    ;(ToolsObserve as any).getUITreeHandler = origGetTree
+  }
+}
+
+run().catch(console.error)

package/test/unit/index.ts

@@ -12,5 +12,7 @@ import '../manage/unit/detection.test.ts'
 import '../manage/unit/mcp_disable_autodetect.test.ts'
 import '../interact/unit/wait_for_screen_change.test.ts'
 import '../observe/unit/capture_debug_snapshot.test.ts'
+import '../observe/unit/find_element.test.ts'
+import '../interact/unit/observe_until.test.ts'
 
 console.log('Unit tests loaded.')