mobile-debug-mcp 0.25.1 → 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;
@@ -135,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,
@@ -876,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 = {

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) {
@@ -438,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`."
             };
         }
@@ -485,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.`
                 };
             }
@@ -511,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.1'
+    version: '0.26.0'
 };
 export function createServer() {
     const server = new Server(serverInfo, {

package/docs/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to the **Mobile Debug MCP** project will be documented in this file.
 
+## [0.26.0]
+- RFC-003 wait/synchronization contract with `snapshot_revision`, `captured_at_ms`, and `loading_state`
+- Added `wait_for_ui_change` for stable in-place UI mutations
+- Updated `get_ui_tree` and `capture_debug_snapshot` to surface snapshot metadata
+- Emulator-validated the new UI-change flow against the Modul8 app
+
 ## [0.25.1]
 - Platform-native element identity metadata for UI targeting
 - Hierarchy-independent element references