mobile-debug-mcp 0.25.0 → 0.26.0

package/dist/interact/index.js

@@ -4,9 +4,11 @@ import { iOSInteract } from './ios.js';
 export { AndroidInteract, iOSInteract };
 import { resolveTargetDevice } from '../utils/resolve-device.js';
 import { ToolsObserve } from '../observe/index.js';
+import { computeSnapshotSignature } from '../observe/snapshot-metadata.js';
 import { nextActionId } from '../server/common.js';
 export class ToolsInteract {
     static _maxResolvedUiElements = 256;
+    static _uiChangeKinds = ['hierarchy_diff', 'text_change', 'state_change'];
     static _sliderSearchLookahead = 8;
     static _sliderNegativeGapTolerancePx = 32;
     static _sliderPositiveGapLimitPx = 640;
@@ -34,6 +36,9 @@ export class ToolsInteract {
             return null;
         return normalized;
     }
+    static _hash(value) {
+        return createHash('sha256').update(JSON.stringify(value)).digest('hex');
+    }
     static _matchesSelector(el, selector) {
         if (!selector)
             return false;
@@ -105,7 +110,13 @@ export class ToolsInteract {
             class: el.type ?? el.class ?? null,
             bounds,
             index,
-            elementId
+            elementId,
+            state: el.state ?? null,
+            stable_id: el.stable_id ?? null,
+            role: el.role ?? null,
+            test_tag: el.test_tag ?? null,
+            selector: el.selector ?? null,
+            semantic: el.semantic ?? null
         };
     }
     static _rememberResolvedElement(elementId, context) {
@@ -129,6 +140,52 @@ export class ToolsInteract {
             return null;
         }
     }
+    static _buildUiChangeSignatures(tree) {
+        const elements = Array.isArray(tree?.elements) ? tree.elements : [];
+        const textPayload = [];
+        const statePayload = [];
+        for (const el of elements) {
+            textPayload.push({
+                text: ToolsInteract._normalize(el?.text ?? el?.label ?? el?.value ?? ''),
+                contentDescription: ToolsInteract._normalize(el?.contentDescription ?? el?.contentDesc ?? el?.accessibilityLabel ?? ''),
+                resourceId: ToolsInteract._normalize(el?.resourceId ?? el?.resourceID ?? el?.id ?? '')
+            });
+            statePayload.push({
+                checked: el?.state?.checked ?? null,
+                selected: el?.state?.selected ?? null,
+                focused: el?.state?.focused ?? null,
+                expanded: el?.state?.expanded ?? null,
+                enabled: el?.state?.enabled ?? null,
+                text_value: el?.state?.text_value ?? null,
+                value: el?.state?.value ?? null,
+                raw_value: el?.state?.raw_value ?? null,
+                value_range: el?.state?.value_range ?? null
+            });
+        }
+        return {
+            hierarchy: computeSnapshotSignature(tree),
+            text: ToolsInteract._hash({
+                screen: ToolsInteract._normalize(tree?.screen),
+                elements: textPayload
+            }),
+            state: ToolsInteract._hash({
+                screen: ToolsInteract._normalize(tree?.screen),
+                elements: statePayload
+            })
+        };
+    }
+    static _matchesUiChange(expected, initial, current) {
+        const candidates = expected ? [expected] : ToolsInteract._uiChangeKinds;
+        for (const changeKind of candidates) {
+            if (changeKind === 'hierarchy_diff' && initial.hierarchy !== current.hierarchy)
+                return changeKind;
+            if (changeKind === 'text_change' && initial.text !== current.text)
+                return changeKind;
+            if (changeKind === 'state_change' && initial.state !== current.state)
+                return changeKind;
+        }
+        return null;
+    }
     static _resolvedTargetFromElement(elementId, element, index) {
         return {
             elementId,
@@ -138,7 +195,12 @@ export class ToolsInteract {
             class: element.type ?? element.class ?? null,
             bounds: ToolsInteract._normalizeBounds(element.bounds),
             index,
-            state: element.state ?? null
+            state: element.state ?? null,
+            stable_id: element.stable_id ?? null,
+            role: element.role ?? null,
+            test_tag: element.test_tag ?? null,
+            selector: element.selector ?? null,
+            semantic: element.semantic ?? null
         };
     }
     static _actionFailure(actionId, timestamp, actionType, selector, resolved, failureCode, retryable, uiFingerprintBefore, uiFingerprintAfter) {
@@ -542,6 +604,11 @@ export class ToolsInteract {
             bounds: boundsObj,
             clickable: !!best.clickable,
             enabled: !!best.enabled,
+            stable_id: best.stable_id ?? null,
+            role: best.role ?? null,
+            test_tag: best.test_tag ?? null,
+            selector: best.selector ?? null,
+            semantic: best.semantic ?? null,
             tapCoordinates,
             telemetry: {
                 matchedIndex: best?._index ?? null,
@@ -860,6 +927,68 @@ export class ToolsInteract {
             }
         };
     }
+    static async waitForUIChangeHandler({ platform, deviceId, timeout_ms = 60000, stability_window_ms = 250, expected_change }) {
+        const start = Date.now();
+        const pollIntervalMs = 300;
+        const stabilityWindow = Math.max(0, typeof stability_window_ms === 'number' ? stability_window_ms : 250);
+        let baseline = null;
+        let lastObservedRevision = null;
+        let lastLoadingState = null;
+        while (Date.now() - start < timeout_ms) {
+            try {
+                const tree = await ToolsObserve.getUITreeHandler({ platform, deviceId });
+                const signatures = ToolsInteract._buildUiChangeSignatures(tree);
+                lastObservedRevision = typeof tree?.snapshot_revision === 'number' ? tree.snapshot_revision : lastObservedRevision;
+                lastLoadingState = tree?.loading_state ?? lastLoadingState;
+                if (!baseline) {
+                    baseline = signatures;
+                }
+                else {
+                    const observedChange = ToolsInteract._matchesUiChange(expected_change, baseline, signatures);
+                    if (observedChange) {
+                        if (stabilityWindow > 0) {
+                            await new Promise(resolve => setTimeout(resolve, stabilityWindow));
+                            const confirmTree = await ToolsObserve.getUITreeHandler({ platform, deviceId });
+                            const confirmSignatures = ToolsInteract._buildUiChangeSignatures(confirmTree);
+                            const confirmChange = ToolsInteract._matchesUiChange(expected_change, baseline, confirmSignatures);
+                            if (!confirmChange || confirmSignatures.hierarchy !== signatures.hierarchy || confirmSignatures.text !== signatures.text || confirmSignatures.state !== signatures.state) {
+                                lastObservedRevision = typeof confirmTree?.snapshot_revision === 'number' ? confirmTree.snapshot_revision : lastObservedRevision;
+                                lastLoadingState = confirmTree?.loading_state ?? lastLoadingState;
+                                await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
+                                continue;
+                            }
+                            lastObservedRevision = typeof confirmTree?.snapshot_revision === 'number' ? confirmTree.snapshot_revision : lastObservedRevision;
+                            lastLoadingState = confirmTree?.loading_state ?? lastLoadingState;
+                        }
+                        return {
+                            success: true,
+                            observed_change: observedChange,
+                            snapshot_revision: lastObservedRevision ?? undefined,
+                            timeout: false,
+                            elapsed_ms: Date.now() - start,
+                            expected_change,
+                            loading_state: lastLoadingState ?? null,
+                            reason: 'UI change observed'
+                        };
+                    }
+                }
+            }
+            catch {
+                // Keep polling until timeout; the observable surface should be best-effort.
+            }
+            await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
+        }
+        return {
+            success: false,
+            observed_change: null,
+            snapshot_revision: lastObservedRevision ?? undefined,
+            timeout: true,
+            elapsed_ms: Date.now() - start,
+            expected_change,
+            loading_state: lastLoadingState ?? null,
+            reason: 'timeout'
+        };
+    }
     static async expectScreenHandler({ platform, fingerprint, screen, deviceId }) {
         const observedFingerprint = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId });
         const observedScreen = {
@@ -940,7 +1069,12 @@ export class ToolsInteract {
                     class: result.element.class ?? null,
                     bounds: result.element.bounds ?? null,
                     index: typeof result.element.index === 'number' ? result.element.index : null,
-                    state: result.element.state ?? null
+                    state: result.element.state ?? null,
+                    stable_id: result.element.stable_id ?? null,
+                    role: result.element.role ?? null,
+                    test_tag: result.element.test_tag ?? null,
+                    selector: result.element.selector ?? null,
+                    semantic: result.element.semantic ?? null
                 },
                 observed: {
                     status: result.status,
@@ -955,7 +1089,12 @@ export class ToolsInteract {
                         class: result.element.class ?? null,
                         bounds: result.element.bounds ?? null,
                         index: typeof result.element.index === 'number' ? result.element.index : null,
-                        state: result.element.state ?? null
+                        state: result.element.state ?? null,
+                        stable_id: result.element.stable_id ?? null,
+                        role: result.element.role ?? null,
+                        test_tag: result.element.test_tag ?? null,
+                        selector: result.element.selector ?? null,
+                        semantic: result.element.semantic ?? null
                     }
                 },
                 reason: 'selector is visible'

package/dist/observe/android.js

@@ -6,6 +6,7 @@ import { promises as fsPromises } from "fs";
 import path from "path";
 import { computeScreenFingerprint } from "../utils/ui/index.js";
 import { parsePngSize } from "../utils/image.js";
+import { deriveSnapshotMetadata } from "./snapshot-metadata.js";
 const activeLogStreams = new Map();
 export class AndroidObserve {
     async getDeviceMetadata(appId, deviceId) {
@@ -61,21 +62,29 @@ export class AndroidObserve {
                     traverseNode(result.hierarchy.node, elements);
                 }
             }
+            const snapshotMetadata = deriveSnapshotMetadata(`android:${deviceInfo.id}`, {
+                screen: "",
+                resolution,
+                elements
+            }, 'ui_tree');
             return {
                 device: deviceInfo,
                 screen: "",
                 resolution,
-                elements
+                elements,
+                ...snapshotMetadata
             };
         }
         catch (e) {
             const errorMessage = `Failed to get UI tree. ADB Path: '${getAdbCmd()}'. Error: ${e instanceof Error ? e.message : String(e)}`;
             console.error(errorMessage);
+            const snapshotMetadata = deriveSnapshotMetadata(`android:${deviceInfo.id}`, null, 'ui_tree');
             return {
                 device: deviceInfo,
                 screen: "",
                 resolution: { width: 0, height: 0 },
                 elements: [],
+                ...snapshotMetadata,
                 error: errorMessage
             };
         }

package/dist/observe/index.js

@@ -1,6 +1,7 @@
 import { resolveTargetDevice } from '../utils/resolve-device.js';
 import { AndroidObserve } from './android.js';
 import { iOSObserve } from './ios.js';
+import { deriveSnapshotMetadata } from './snapshot-metadata.js';
 export { AndroidObserve } from './android.js';
 export { iOSObserve } from './ios.js';
 function normalizeHint(value) {
@@ -200,7 +201,17 @@ export class ToolsObserve {
     }
     static async captureDebugSnapshotHandler({ reason, includeLogs = true, logLines = 200, platform, appId, deviceId, sessionId } = {}) {
         const timestamp = Date.now();
-        const raw = { timestamp, reason: reason || '', activity: null, fingerprint: null, screenshot: null, ui_tree: null, logs: [] };
+        const raw = {
+            timestamp,
+            snapshot_revision: 0,
+            captured_at_ms: timestamp,
+            reason: reason || '',
+            activity: null,
+            fingerprint: null,
+            screenshot: null,
+            ui_tree: null,
+            logs: []
+        };
         // Parallel fetches for performance: screenshot, current screen, fingerprint, ui tree, and log stream/get logs
         const sid = sessionId || 'default';
         const tasks = {
@@ -308,6 +319,13 @@ export class ToolsObserve {
                 raw.logs_error = e instanceof Error ? e.message : String(e);
             }
         }
+        const snapshotDeviceKey = raw.ui_tree?.device
+            ? `${raw.ui_tree.device.platform}:${raw.ui_tree.device.id}`
+            : `${platform || 'unknown'}:${deviceId || 'default'}`;
+        const snapshotMetadata = deriveSnapshotMetadata(snapshotDeviceKey, raw.ui_tree, 'snapshot', raw.ui_tree?.snapshot_revision ? null : (raw.fingerprint || raw.activity || null));
+        raw.snapshot_revision = raw.ui_tree?.snapshot_revision ?? snapshotMetadata.snapshot_revision;
+        raw.captured_at_ms = raw.ui_tree?.captured_at_ms ?? snapshotMetadata.captured_at_ms;
+        raw.loading_state = raw.ui_tree?.loading_state ?? snapshotMetadata.loading_state;
         const semantic = deriveSnapshotSemantic(raw);
         return semantic ? { raw, semantic } : { raw };
     }

package/dist/observe/ios.js

@@ -6,6 +6,7 @@ import path from 'path';
 import { parseLogLine } from '../utils/android/utils.js';
 import { computeScreenFingerprint } from '../utils/ui/index.js';
 import { parsePngSize } from '../utils/image.js';
+import { deriveSnapshotMetadata } from './snapshot-metadata.js';
 const delay = (ms) => new Promise(resolve => setTimeout(resolve, ms));
 let iosExecCommand = execCommand;
 export function _setIOSExecCommandForTests(fn) {
@@ -45,6 +46,65 @@ function parseIOSNumber(value) {
     const parsed = Number(value);
     return Number.isFinite(parsed) ? parsed : null;
 }
+function normalizeIOSType(value) {
+    return typeof value === 'string' ? value.trim().toLowerCase() : '';
+}
+function inferIOSRole(type, traits) {
+    if (/slider|adjustable/.test(type) || traits.some((trait) => /adjustable|slider/.test(trait)))
+        return 'slider';
+    if (/button/.test(type) || traits.some((trait) => /button/.test(trait)))
+        return 'button';
+    if (/cell/.test(type))
+        return 'cell';
+    if (/switch/.test(type))
+        return 'switch';
+    if (/text field|textfield|search field/.test(type))
+        return 'text_field';
+    if (/image/.test(type))
+        return 'image';
+    if (/window|application|group|scroll view|collection view/.test(type))
+        return 'container';
+    return null;
+}
+function getIOSStableId(node) {
+    const candidates = [node.AXIdentifier, node.accessibilityIdentifier, node.identifier, node.AXUniqueId];
+    for (const candidate of candidates) {
+        if (typeof candidate === 'string' && candidate.trim().length > 0)
+            return candidate;
+    }
+    return null;
+}
+function buildIOSSelectorConfidence(source) {
+    switch (source) {
+        case 'identifier':
+            return { score: 1, reason: 'accessibility_identifier' };
+        case 'label':
+            return { score: 0.9, reason: 'label_match' };
+        case 'value':
+            return { score: 0.75, reason: 'value_match' };
+        case 'type':
+            return { score: 0.35, reason: 'type_match' };
+        default:
+            return null;
+    }
+}
+function buildIOSSelector(type, label, value, stableId) {
+    if (stableId)
+        return { value: stableId, confidence: buildIOSSelectorConfidence('identifier') };
+    if (label)
+        return { value: label, confidence: buildIOSSelectorConfidence('label') };
+    if (value)
+        return { value: value, confidence: buildIOSSelectorConfidence('value') };
+    if (type)
+        return { value: type, confidence: buildIOSSelectorConfidence('type') };
+    return null;
+}
+function buildIOSSemantic(type, traits) {
+    return {
+        is_clickable: traits.includes("UIAccessibilityTraitButton") || /adjustable|slider/.test(type) || type === "Button" || type === "Cell",
+        is_container: /window|application|group|scroll view|collection view/.test(type)
+    };
+}
 function isIOSAdjustable(node, type, traits) {
     return /slider|adjustable|stepper|progress/i.test(type) || traits.some((trait) => /adjustable|slider|progress/i.test(trait));
 }
@@ -99,6 +159,11 @@ export function traverseIDBNode(node, elements, parentIndex = -1, depth = 0) {
     const frame = node.AXFrame || node.frame;
     const traits = node.AXTraits || [];
     const state = extractIOSState(node, type, label, value, traits);
+    const normalizedType = normalizeIOSType(type);
+    const stableId = getIOSStableId(node);
+    const selector = buildIOSSelector(type, label, value, stableId);
+    const semantic = buildIOSSemantic(normalizedType, traits);
+    const role = inferIOSRole(normalizedType, traits);
     const clickable = traits.includes("UIAccessibilityTraitButton") || type === "Button" || type === "Cell";
     const isUseful = clickable || (label && label.length > 0) || (value && value.length > 0) || type === "Application" || type === "Window";
     if (isUseful) {
@@ -107,14 +172,19 @@ export function traverseIDBNode(node, elements, parentIndex = -1, depth = 0) {
             text: label,
             contentDescription: value,
             type: type,
-            resourceId: node.AXUniqueId || null,
+            resourceId: stableId,
             clickable: clickable,
             enabled: true,
             visible: true,
             bounds: bounds,
             center: getCenter(bounds),
             depth: depth,
-            state
+            state,
+            stable_id: stableId,
+            role,
+            test_tag: stableId,
+            selector,
+            semantic
         };
         if (parentIndex !== -1) {
             element.parentId = parentIndex;
@@ -369,13 +439,16 @@ export class iOSObserve {
     }
     async getUITree(deviceId = "booted") {
         const device = await getIOSDeviceMetadata(deviceId);
+        const deviceKey = `ios:${device.id}`;
         const idbExists = await isIDBInstalled();
         if (!idbExists) {
+            const snapshotMetadata = deriveSnapshotMetadata(deviceKey, null, 'ui_tree');
             return {
                 device,
                 screen: "",
                 resolution: { width: 0, height: 0 },
                 elements: [],
+                ...snapshotMetadata,
                 error: "iOS UI tree retrieval requires 'idb' (iOS Device Bridge). Please install it via Homebrew: `brew tap facebook/fb && brew install idb-companion` and `pip3 install fb-idb`."
             };
         }
@@ -416,11 +489,13 @@ export class iOSObserve {
                 console.error(`Attempt ${attempts} failed: ${e}`);
             }
             if (attempts === maxAttempts) {
+                const snapshotMetadata = deriveSnapshotMetadata(deviceKey, null, 'ui_tree');
                 return {
                     device,
                     screen: "",
                     resolution: { width: 0, height: 0 },
                     elements: [],
+                    ...snapshotMetadata,
                     error: `Failed to retrieve valid UI dump after ${maxAttempts} attempts.`
                 };
             }
@@ -442,19 +517,27 @@ export class iOSObserve {
                 width = rootBounds[2] - rootBounds[0];
                 height = rootBounds[3] - rootBounds[1];
             }
+            const snapshotMetadata = deriveSnapshotMetadata(deviceKey, {
+                screen: "",
+                resolution: { width, height },
+                elements
+            }, 'ui_tree');
             return {
                 device,
                 screen: "",
                 resolution: { width, height },
-                elements
+                elements,
+                ...snapshotMetadata
             };
         }
         catch (e) {
+            const snapshotMetadata = deriveSnapshotMetadata(deviceKey, null, 'ui_tree');
             return {
                 device,
                 screen: "",
                 resolution: { width: 0, height: 0 },
                 elements: [],
+                ...snapshotMetadata,
                 error: `Failed to parse idb output: ${e instanceof Error ? e.message : String(e)}`
             };
         }

package/dist/observe/snapshot-metadata.js

@@ -0,0 +1,88 @@
+import crypto from 'crypto';
+const snapshotStateByDevice = new Map();
+function normalize(value) {
+    if (value === null || value === undefined)
+        return '';
+    return String(value).trim().toLowerCase();
+}
+function normalizeBounds(bounds) {
+    if (!Array.isArray(bounds) || bounds.length < 4)
+        return null;
+    const normalized = bounds.slice(0, 4).map((value) => Number(value));
+    if (normalized.some((value) => Number.isNaN(value)))
+        return null;
+    return normalized;
+}
+function stableElementSignature(element) {
+    return {
+        text: normalize(element.text),
+        contentDescription: normalize(element.contentDescription),
+        resourceId: normalize(element.resourceId),
+        type: normalize(element.type),
+        stable_id: normalize(element.stable_id),
+        role: normalize(element.role),
+        test_tag: normalize(element.test_tag),
+        selector: normalize(element.selector?.value),
+        clickable: !!element.clickable,
+        enabled: !!element.enabled,
+        visible: !!element.visible,
+        state: element.state ?? null,
+        bounds: normalizeBounds(element.bounds)
+    };
+}
+export function computeSnapshotSignature(tree) {
+    if (!tree || tree.error)
+        return null;
+    const payload = {
+        screen: normalize(tree.screen),
+        resolution: tree.resolution || { width: 0, height: 0 },
+        elements: Array.isArray(tree.elements) ? tree.elements.map((element) => stableElementSignature(element)) : []
+    };
+    return crypto.createHash('sha256').update(JSON.stringify(payload)).digest('hex');
+}
+export function detectLoadingState(tree, source) {
+    if (!tree || tree.error || !Array.isArray(tree.elements))
+        return null;
+    for (const element of tree.elements) {
+        if (!element?.visible)
+            continue;
+        const text = normalize(element?.text ?? element?.contentDescription ?? '');
+        const type = normalize(element?.type ?? '');
+        const combined = `${type} ${text}`;
+        if (/progress|spinner|loading|please wait|busy|loading indicator|skeleton|pending/.test(combined)) {
+            const signal = /progress/.test(combined)
+                ? 'progress_indicator'
+                : /spinner/.test(combined)
+                    ? 'spinner'
+                    : /busy/.test(combined)
+                        ? 'busy_indicator'
+                        : /skeleton/.test(combined)
+                            ? 'skeleton'
+                            : 'loading_indicator';
+            return { active: true, signal, source };
+        }
+    }
+    return null;
+}
+export function deriveSnapshotMetadata(deviceKey, tree, source, signatureOverride) {
+    const signature = signatureOverride ?? computeSnapshotSignature(tree);
+    const previous = snapshotStateByDevice.get(deviceKey);
+    let revision = 1;
+    if (previous) {
+        if (signature === null) {
+            revision = previous.revision;
+        }
+        else {
+            revision = previous.signature === signature ? previous.revision : previous.revision + 1;
+        }
+    }
+    snapshotStateByDevice.set(deviceKey, { revision, signature });
+    return {
+        snapshot_revision: revision,
+        captured_at_ms: Date.now(),
+        loading_state: detectLoadingState(tree, source)
+    };
+}
+export function resetSnapshotMetadataForTests() {
+    snapshotStateByDevice.clear();
+}

package/dist/server/tool-definitions.js

@@ -240,7 +240,7 @@ Failure Handling:
     },
     {
         name: 'capture_debug_snapshot',
-        description: 'Capture a complete debug snapshot (raw observation layer plus optional derived semantic layer). Returns structured JSON.',
+        description: 'Capture a complete debug snapshot (raw observation layer plus optional derived semantic layer). Returns structured JSON with snapshot_revision, captured_at_ms, and loading_state when detectable.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -291,7 +291,7 @@ Failure Handling:
     },
     {
         name: 'get_ui_tree',
-        description: 'Get the current UI hierarchy from an Android device or iOS simulator. Returns a structured JSON representation of the screen content.',
+        description: 'Get the current UI hierarchy from an Android device or iOS simulator. Returns a structured JSON representation of the screen content with snapshot metadata when available.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -363,6 +363,34 @@ Recommended Usage:
             required: ['previousFingerprint']
         }
     },
+    {
+        name: 'wait_for_ui_change',
+        description: `Purpose:
+Wait for a non-navigation UI mutation or in-place update to become stable.
+
+Inputs:
+- expected_change (optional): hierarchy_diff, text_change, or state_change
+- timeout_ms (optional)
+- stability_window_ms (optional)
+
+Guidance:
+- Prefer wait_for_screen_change for navigation transitions.
+- Prefer wait_for_ui_change for in-place mutations and non-navigation updates.
+- Use the returned snapshot_revision as the observed synchronization point when available.
+
+Failure Handling:
+- TIMEOUT means the UI did not change in a stable way within the allotted time.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                platform: { type: 'string', enum: ['android', 'ios'], description: 'Optional platform override (android|ios)' },
+                deviceId: { type: 'string', description: 'Optional device id/udid to target' },
+                expected_change: { type: 'string', enum: ['hierarchy_diff', 'text_change', 'state_change'], description: 'Optional type of UI change to wait for' },
+                timeout_ms: { type: 'number', description: 'Timeout in ms to wait for change (default 60000)', default: 60000 },
+                stability_window_ms: { type: 'number', description: 'How long the change must remain stable before success (default 250)', default: 250 }
+            }
+        }
+    },
     {
         name: 'expect_screen',
         description: `Purpose:

package/dist/server/tool-handlers.js

@@ -236,6 +236,15 @@ async function handleWaitForUI(args) {
     const res = await ToolsInteract.waitForUIHandler({ selector, condition, timeout_ms, poll_interval_ms, match, retry, platform, deviceId });
     return wrapResponse(res);
 }
+async function handleWaitForUIChange(args) {
+    const platform = getStringArg(args, 'platform');
+    const deviceId = getStringArg(args, 'deviceId');
+    const timeout_ms = getNumberArg(args, 'timeout_ms') ?? 60000;
+    const stability_window_ms = getNumberArg(args, 'stability_window_ms') ?? 250;
+    const expected_change = getStringArg(args, 'expected_change');
+    const res = await ToolsInteract.waitForUIChangeHandler({ platform, deviceId, timeout_ms, stability_window_ms, expected_change });
+    return wrapResponse(res);
+}
 async function handleFindElement(args) {
     const query = requireStringArg(args, 'query');
     const exact = getBooleanArg(args, 'exact') ?? false;
@@ -409,6 +418,7 @@ export const toolHandlers = {
     get_current_screen: handleGetCurrentScreen,
     get_screen_fingerprint: handleGetScreenFingerprint,
     wait_for_screen_change: handleWaitForScreenChange,
+    wait_for_ui_change: handleWaitForUIChange,
     expect_screen: handleExpectScreen,
     expect_element_visible: handleExpectElementVisible,
     expect_state: handleExpectState,

package/dist/server-core.js

@@ -6,7 +6,7 @@ import { handleToolCall } from './server/tool-handlers.js';
 export { wrapResponse, toolDefinitions, handleToolCall };
 export const serverInfo = {
     name: 'mobile-debug-mcp',
-    version: '0.25.0'
+    version: '0.26.0'
 };
 export function createServer() {
     const server = new Server(serverInfo, {