mobile-debug-mcp 0.20.1 → 0.21.1

package/dist/interact/android.js

@@ -3,33 +3,6 @@ import { AndroidObserve } from "../observe/index.js";
 import { scrollToElementShared } from "../utils/ui/index.js";
 export class AndroidInteract {
     observe = new AndroidObserve();
-    async waitForElement(text, timeout, deviceId) {
-        const metadata = await getAndroidDeviceMetadata("", deviceId);
-        const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
-        const startTime = Date.now();
-        while (Date.now() - startTime < timeout) {
-            try {
-                const tree = await this.observe.getUITree(deviceId);
-                if (tree.error) {
-                    return { device: deviceInfo, found: false, error: tree.error };
-                }
-                const element = tree.elements.find(e => e.text === text);
-                if (element) {
-                    return { device: deviceInfo, found: true, element };
-                }
-            }
-            catch (e) {
-                // Ignore errors during polling and retry
-                console.error("Error polling UI tree:", e);
-            }
-            const elapsed = Date.now() - startTime;
-            const remaining = timeout - elapsed;
-            if (remaining <= 0)
-                break;
-            await new Promise(resolve => setTimeout(resolve, Math.min(500, remaining)));
-        }
-        return { device: deviceInfo, found: false };
-    }
     async tap(x, y, deviceId) {
         const metadata = await getAndroidDeviceMetadata("", deviceId);
         const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);

package/dist/interact/index.js

@@ -3,7 +3,6 @@ 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';
@@ -11,11 +10,6 @@ export class ToolsInteract {
         const interact = effectivePlatform === 'android' ? new AndroidInteract() : new iOSInteract();
         return { interact: interact, resolved, platform: effectivePlatform };
     }
-    static async waitForElementHandler({ platform, text, timeout, deviceId }) {
-        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 }) {
         const { interact, resolved } = await ToolsInteract.getInteractionService(platform, deviceId);
         return await interact.tap(x, y, resolved.id);
@@ -221,6 +215,10 @@ export class ToolsInteract {
         const scoreVal = Math.min(1, Number(bestScore.toFixed(3)));
         return { found: true, element: outEl, score: scoreVal, confidence: scoreVal };
     }
+    static async waitForUIHandler({ type = 'ui', query, timeoutMs = 30000, pollIntervalMs = 300, includeSnapshotOnFailure = true, match = 'present', stability_ms = 700, observationDelayMs = 0, platform, deviceId }) {
+        // Backwards-compatible wrapper that delegates to the core waitForUICore implementation
+        return await ToolsInteract.waitForUICore({ type, query, timeoutMs, pollIntervalMs, includeSnapshotOnFailure, match, stability_ms, observationDelayMs, platform, deviceId });
+    }
     static async waitForScreenChangeHandler({ platform, previousFingerprint, timeoutMs = 5000, pollIntervalMs = 300, deviceId }) {
         const start = Date.now();
         let lastFingerprint = null;
@@ -259,167 +257,190 @@ export class ToolsInteract {
         }
         return { success: false, reason: 'timeout', lastFingerprint, elapsedMs: Date.now() - start };
     }
-    static async observeUntilHandler({ type, query, timeoutMs = 5000, pollIntervalMs = 200, platform, deviceId }) {
+    static async waitForUICore({ type = 'ui', query, timeoutMs = 30000, pollIntervalMs = 300, includeSnapshotOnFailure = true, match = 'present', stability_ms = 700, observationDelayMs = 0, platform, deviceId }) {
         const start = Date.now();
         const deadline = start + (timeoutMs || 0);
         const q = (query === null || query === undefined) ? '' : String(query);
-        // Baseline state
+        // Clamp polling interval to 250-500ms for consistent behavior
+        const pollInterval = Math.max(250, Math.min(pollIntervalMs || 300, 500));
+        // Baseline state (fetch in parallel but bound to short timeouts so observation starts promptly)
         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;
+            const fpPromise = ToolsObserve.getScreenFingerprintHandler({ platform, deviceId });
+            const logsPromise = ToolsObserve.getLogsHandler({ platform, deviceId, lines: 200 });
+            const withTimeout = (p, ms) => Promise.race([p, new Promise(resolve => setTimeout(() => resolve(null), ms))]);
+            const [fpRes, gl] = await Promise.all([withTimeout(fpPromise, 300), withTimeout(logsPromise, 500)]);
+            if (fpRes && typeof fpRes === 'object')
+                initialFingerprint = fpRes.fingerprint ?? null;
+            if (gl) {
+                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));
+                console.warn('waitForUI: failed to get baseline data (non-fatal):', err instanceof Error ? err.message : String(err));
             }
             catch { }
         }
+        // Network-based waiting removed. Rely on UI and screen fingerprints for determinism.
         let lastChangeAt = Date.now();
         let prevFingerprint = initialFingerprint;
         const sleep = (ms) => new Promise(r => setTimeout(r, ms));
+        // Optional initial observation delay requested by caller
+        if (typeof observationDelayMs === 'number' && observationDelayMs > 0) {
+            try {
+                console.log(`waitForUI: delaying observation for ${observationDelayMs}ms`);
+            }
+            catch { }
+            await sleep(observationDelayMs);
+        }
         // Telemetry
         let pollCount = 0;
-        let timeToMatch = null;
+        let matchedAt = null;
+        let lastObservedState = null;
+        let stableDuration = 0;
         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') {
+            const now = Date.now();
+            // Evaluate condition per type
+            if (type === 'ui') {
+                try {
+                    // Prefer using the public findElementHandler which tests can override. This avoids relying
+                    // on resolveObserve/getUITree for unit tests which may not have devices available.
                     try {
-                        // 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 } };
+                        const findRes = await ToolsInteract.findElementHandler({ query: q, exact: false, timeoutMs: Math.min(500, pollInterval), platform, deviceId });
+                        const isPresent = !!(findRes && findRes.found);
+                        const conditionTrue = (match === 'present') ? isPresent : !isPresent;
+                        if (conditionTrue) {
+                            if (matchedAt === null)
+                                matchedAt = Date.now();
+                            stableDuration = Date.now() - matchedAt;
+                            lastObservedState = true;
+                            if (stableDuration >= stability_ms) {
+                                matchSource = 'ui-find';
+                                const element = isPresent ? findRes.element : null;
+                                const now2 = Date.now();
+                                return { success: true, condition: match, query: q, poll_count: pollCount, duration_ms: now2 - start, stable_duration_ms: stableDuration, matchedElement: element, matchSource, timestamp: now2, type: 'ui', observed_state: lastObservedState ?? null };
                             }
                         }
-                        // 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 } };
-                            }
+                        else {
+                            matchedAt = null;
+                            stableDuration = 0;
+                            lastObservedState = false;
                         }
                     }
                     catch (err) {
-                        console.error('observeUntil(log) error:', err);
+                        console.error('waitForUI(ui) find 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('waitForUI(ui) outer error:', err);
+                }
+            }
+            else if (type === 'log') {
+                try {
+                    // Logs: presence semantics only (match 'present'). Stability not applicable (immediate)
+                    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)) {
+                            const now2 = Date.now();
+                            return { success: true, condition: 'present', query: q, poll_count: pollCount, duration_ms: now2 - start, stable_duration_ms: 0, matchedLog: { message: msg, raw: ent }, matchSource: 'log-stream', timestamp: now2, type: 'log', observed_state: true };
                         }
                     }
-                    catch (err) {
-                        console.error('observeUntil(screen) error:', err);
+                    const gl = await ToolsObserve.getLogsHandler({ platform, deviceId, lines: 200 });
+                    const logsArr = Array.isArray(gl && gl.logs) ? gl.logs : [];
+                    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)) {
+                            const now2 = Date.now();
+                            return { success: true, condition: 'present', query: q, poll_count: pollCount, duration_ms: now2 - start, stable_duration_ms: 0, matchedLog: { message: line }, matchSource: 'log-snapshot', timestamp: now2, type: 'log', observed_state: true };
+                        }
                     }
                 }
-                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();
+                catch (err) {
+                    console.error('waitForUI(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) {
+                        // when screen changed, require stability_ms where fingerprint remains the same
+                        if (matchedAt === null)
+                            matchedAt = now;
+                        const confirmFp = (await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId }))?.fingerprint ?? null;
+                        if (confirmFp === fp) {
+                            stableDuration = Date.now() - matchedAt;
+                            lastObservedState = true;
+                            if (stableDuration >= stability_ms) {
+                                const now2 = Date.now();
+                                return { success: true, condition: 'present', query: q, poll_count: pollCount, duration_ms: now2 - start, stable_duration_ms: stableDuration, newFingerprint: fp, matchSource: 'screen-fingerprint', timestamp: now2, type: 'screen', observed_state: lastObservedState ?? null };
+                            }
                         }
                         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 } };
-                            }
+                            matchedAt = null;
+                            stableDuration = 0;
+                            lastObservedState = false;
                         }
                     }
-                    catch (err) {
-                        console.error('observeUntil(idle) error:', err);
-                    }
+                }
+                catch (err) {
+                    console.error('waitForUI(screen) error:', err);
                 }
             }
-            catch (err) {
-                console.error('observeUntil: unexpected 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();
+                        matchedAt = null;
+                        stableDuration = 0;
+                        lastObservedState = false;
+                    }
+                    else {
+                        const idleMs = Date.now() - lastChangeAt;
+                        lastObservedState = true;
+                        if (idleMs >= stability_ms) {
+                            const now2 = Date.now();
+                            return { success: true, condition: 'present', query: q, poll_count: pollCount, duration_ms: now2 - start, stable_duration_ms: idleMs, matchSource: 'idle-stable', timestamp: now2, type: 'idle', observed_state: lastObservedState ?? null };
+                        }
+                    }
+                }
+                catch (err) {
+                    console.error('waitForUI(idle) error:', err);
+                }
             }
             // Respect poll interval and avoid tight loop
-            await sleep(pollIntervalMs || 200);
+            await sleep(pollInterval);
         }
-        // On timeout, capture a failure snapshot to aid debugging (best-effort)
+        // On timeout, optionally 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) };
+        if (includeSnapshotOnFailure) {
+            try {
+                // Use dynamic import to avoid circular-initialization issues where the ToolsObserve
+                // binding captured earlier may not reflect test-time overrides. Importing at call
+                // time ensures the latest exported ToolsObserve object is used.
+                const Obs = await import('../observe/index.js');
+                snapshot = await Obs.ToolsObserve.captureDebugSnapshotHandler({ reason: `wait_for_ui 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 };
+        return { success: false, condition: match, query: q, poll_count: pollCount, duration_ms: elapsed, stable_duration_ms: stableDuration, error: 'Timeout waiting for condition', snapshot, observed_state: lastObservedState ?? null };
     }
 }

package/dist/interact/ios.js

@@ -4,32 +4,6 @@ import { iOSObserve } from "../observe/index.js";
 import { scrollToElementShared } from "../utils/ui/index.js";
 export class iOSInteract {
     observe = new iOSObserve();
-    async waitForElement(text, timeout, deviceId = "booted") {
-        const device = await getIOSDeviceMetadata(deviceId);
-        const startTime = Date.now();
-        while (Date.now() - startTime < timeout) {
-            try {
-                const tree = await this.observe.getUITree(deviceId);
-                if (tree.error) {
-                    return { device, found: false, error: tree.error };
-                }
-                const element = tree.elements.find(e => e.text === text);
-                if (element) {
-                    return { device, found: true, element };
-                }
-            }
-            catch (e) {
-                // Ignore errors during polling and retry
-                console.error("Error polling UI tree:", e);
-            }
-            const elapsed = Date.now() - startTime;
-            const remaining = timeout - elapsed;
-            if (remaining <= 0)
-                break;
-            await new Promise(resolve => setTimeout(resolve, Math.min(500, remaining)));
-        }
-        return { device, found: false };
-    }
     async tap(x, y, deviceId = "booted") {
         const device = await getIOSDeviceMetadata(deviceId);
         // Use shared helper to detect idb

package/dist/scripts/capture_ui_after_tap.mjs

@@ -0,0 +1,43 @@
+import { ToolsObserve } from '../observe/index.js'
+import { ToolsInteract } from '../interact/index.js'
+
+async function main() {
+  const platform = process.argv.includes('--platform') ? process.argv[process.argv.indexOf('--platform')+1] : 'android'
+  const device = process.argv.includes('--device') ? process.argv[process.argv.indexOf('--device')+1] : undefined
+
+  console.log('Tap then capture UI tree snapshots')
+  try {
+    // Tap generate
+    const found = await (await import('../interact/index.js')).ToolsInteract.findElementHandler({ query: 'Generate Session', platform, timeoutMs: 3000, exact: true, deviceId: device })
+    console.log('Found generate?', !!(found && found.found), JSON.stringify(found && found.element || {}))
+    if (found && found.found && found.element && found.element.tapCoordinates) {
+      await (await import('../interact/index.js')).ToolsInteract.tapHandler({ platform, x: found.element.tapCoordinates.x, y: found.element.tapCoordinates.y, deviceId: device })
+      console.log('Tapped Generate at', found.element.tapCoordinates)
+    } else {
+      console.log('Could not find generate element — aborting capture')
+      process.exit(2)
+    }
+
+    // Capture UI trees and screenshot repeatedly for 20s
+    const start = Date.now()
+    const outDir = '/tmp/mcp_ui_captures'
+    try { await import('fs').then(fs=>fs.promises.mkdir(outDir,{recursive:true})) } catch(e){}
+    let i = 0
+    while (Date.now() - start < 20000) {
+      const snap = await ToolsObserve.getUITreeHandler({ platform, deviceId: device })
+      const fname = `${outDir}/ui_${Date.now()}_${i}.json`
+      await import('fs').then(fs=>fs.promises.writeFile(fname, JSON.stringify(snap,null,2)))
+      console.log('Saved', fname)
+      i++
+      await new Promise(r=>setTimeout(r,500))
+    }
+
+    console.log('Capture complete')
+    process.exit(0)
+  } catch (e) {
+    console.error('Error during capture:', e)
+    process.exit(1)
+  }
+}
+
+main()

package/dist/scripts/check_play_observe.mjs

@@ -0,0 +1,18 @@
+import { ToolsInteract } from '../interact/index.js'
+
+async function main() {
+  const platform = process.argv.includes('--platform') ? process.argv[process.argv.indexOf('--platform')+1] : 'android'
+  const device = process.argv.includes('--device') ? process.argv[process.argv.indexOf('--device')+1] : undefined
+  const timeout = parseInt(process.argv.includes('--timeout') ? process.argv[process.argv.indexOf('--timeout')+1] : '120000')
+  console.log('Running observeUntil for Play session, platform=', platform, 'device=', device)
+  try {
+    const res = await ToolsInteract.observeUntilHandler({ type: 'ui', query: 'Play session', match: 'present', timeoutMs: timeout, pollIntervalMs: 300, stability_ms: 700, platform, deviceId: device })
+    console.log('observeUntil result:', JSON.stringify(res, null, 2))
+    process.exit(res && res.success ? 0 : 2)
+  } catch (e) {
+    console.error('Error running observeUntil:', e)
+    process.exit(1)
+  }
+}
+
+main()

package/dist/scripts/check_play_substring.mjs

@@ -0,0 +1,38 @@
+import { ToolsObserve } from '../observe/index.js'
+
+async function main() {
+  const platform = process.argv.includes('--platform') ? process.argv[process.argv.indexOf('--platform')+1] : 'android'
+  const device = process.argv.includes('--device') ? process.argv[process.argv.indexOf('--device')+1] : undefined
+  const timeout = parseInt(process.argv.includes('--timeout') ? process.argv[process.argv.indexOf('--timeout')+1] : '120000')
+  const start = Date.now()
+  const out = []
+  console.log('Searching UI trees for elements containing "play" (case-insensitive)')
+  while (Date.now() - start < timeout) {
+    try {
+      const tree = await ToolsObserve.getUITreeHandler({ platform, deviceId: device })
+      const elements = Array.isArray((tree && tree.elements)) ? tree.elements : []
+      const matches = []
+      const norm = (s)=> s ? String(s).toLowerCase() : ''
+      for (const el of elements) {
+        const text = norm(el.text)
+        const content = norm(el.contentDescription || el.contentDesc || el.accessibilityLabel)
+        const rid = norm(el.resourceId || el.id)
+        const cls = norm(el.type || el.class)
+        if (text.includes('play') || content.includes('play') || rid.includes('play') || cls.includes('play') || text.includes('session') || content.includes('session')) {
+          matches.push({ el: el, foundIn: { text: text.includes('play')? 'text': text.includes('session')? 'text-session': null } })
+        }
+      }
+      if (matches.length) {
+        console.log('Matches found:', JSON.stringify(matches, null, 2))
+        out.push({ ts: Date.now(), matches })
+        break
+      }
+    } catch (e) { console.error('UITree fetch err:', e) }
+    await new Promise(r=>setTimeout(r, 500))
+  }
+  console.log('Search complete. Results count=', out.length)
+  if (out.length > 0) process.exit(0)
+  process.exit(2)
+}
+
+main()

package/dist/scripts/dump_ui_tree.mjs

@@ -0,0 +1,20 @@
+import { ToolsObserve } from '../observe/index.js'
+
+async function main() {
+  const argv = process.argv.slice(2)
+  const opts = {}
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--platform') opts.platform = argv[++i]
+    else if (argv[i] === '--deviceId') opts.deviceId = argv[++i]
+  }
+  try {
+    const tree = await ToolsObserve.getUITreeHandler({ platform: opts.platform || 'android', deviceId: opts.deviceId })
+    console.log(JSON.stringify(tree, null, 2))
+    process.exit(0)
+  } catch (e) {
+    console.error('failed to get ui tree:', e instanceof Error ? e.message : String(e))
+    process.exit(2)
+  }
+}
+
+main()

package/dist/scripts/observe-test.mjs

@@ -0,0 +1,32 @@
+import { ToolsObserve } from '../observe/index.js'
+import { ToolsInteract } from '../interact/index.js'
+
+async function main() {
+  console.log('Starting log stream for com.ideamechanics.modul8')
+  try {
+    const start = await ToolsObserve.startLogStreamHandler({ platform: 'ios', packageName: 'com.ideamechanics.modul8', sessionId: 'test-session' })
+    console.log('startLogStream result:', JSON.stringify(start))
+  } catch (e) {
+    console.error('startLogStream failed:', e instanceof Error ? e.message : String(e))
+  }
+
+  console.log('\nPlease press the Generate Session button in the app now. Observing for network idle (15s timeout)...')
+
+  try {
+    const res = await ToolsInteract.observeUntilHandler({ type: 'network_idle', timeoutMs: 15000, pollIntervalMs: 300, platform: 'ios' })
+    console.log('observeUntil result:')
+    console.log(JSON.stringify(res, null, 2))
+  } catch (e) {
+    console.error('observeUntil failed:', e instanceof Error ? e.message : String(e))
+  }
+
+  console.log('\nStopping log stream (best-effort)')
+  try {
+    const stop = await ToolsObserve.stopLogStreamHandler({ platform: 'ios', sessionId: 'test-session' })
+    console.log('stopLogStream result:', JSON.stringify(stop))
+  } catch (e) { console.error('stopLogStream failed:', e) }
+
+  process.exit(0)
+}
+
+main().catch(err => { console.error(err); process.exit(1) })