mobile-debug-mcp 0.30.0 → 0.30.1

package/dist/interact/index.js

@@ -95,10 +95,68 @@ export class ToolsInteract {
         }
         return null;
     }
+    static _resolveParentIndex(elements, parentId) {
+        if (parentId === undefined || parentId === null)
+            return null;
+        if (typeof parentId === 'number' && Number.isInteger(parentId) && parentId >= 0 && parentId < elements.length) {
+            return parentId;
+        }
+        if (typeof parentId === 'string') {
+            const normalized = ToolsInteract._normalize(parentId);
+            if (!normalized)
+                return null;
+            if (/^\d+$/.test(normalized)) {
+                const index = Number(normalized);
+                if (index >= 0 && index < elements.length)
+                    return index;
+            }
+            const foundIndex = elements.findIndex((el) => {
+                if (!el)
+                    return false;
+                return ToolsInteract._normalize(el.resourceId ?? el.resourceID ?? el.id ?? '') === normalized ||
+                    ToolsInteract._normalize(el.stable_id ?? '') === normalized;
+            });
+            return foundIndex >= 0 ? foundIndex : null;
+        }
+        return null;
+    }
     static _isVisibleElement(el) {
         const bounds = ToolsInteract._normalizeBounds(el.bounds);
         return !!el.visible && !!bounds && bounds[2] > bounds[0] && bounds[3] > bounds[1];
     }
+    static _isTapActionable(el, storedStableId, platform) {
+        if (!ToolsInteract._isVisibleElement(el)) {
+            return { actionable: false, failureCode: 'ELEMENT_NOT_INTERACTABLE', reason: 'element is not visible' };
+        }
+        if (el.enabled === false) {
+            return { actionable: false, failureCode: 'ELEMENT_NOT_INTERACTABLE', reason: 'element is disabled' };
+        }
+        const semanticTapActionable = !!el.semantic && (el.semantic.is_clickable ||
+            (Array.isArray(el.semantic.supported_actions) && el.semantic.supported_actions.some((action) => ToolsInteract._normalize(action) === 'tap')));
+        if (!el.clickable && !(platform === 'ios' && semanticTapActionable)) {
+            return { actionable: false, failureCode: 'ELEMENT_NOT_INTERACTABLE', reason: 'element is not clickable' };
+        }
+        if (storedStableId) {
+            if (!el.stable_id || el.stable_id !== storedStableId) {
+                return { actionable: false, failureCode: 'STALE_REFERENCE', reason: 'element stable_id changed' };
+            }
+        }
+        return { actionable: true };
+    }
+    static _isAdjustableActionable(el, storedStableId) {
+        if (!ToolsInteract._isVisibleElement(el)) {
+            return { actionable: false, failureCode: 'ELEMENT_NOT_INTERACTABLE', reason: 'element is not visible' };
+        }
+        if (el.enabled === false) {
+            return { actionable: false, failureCode: 'ELEMENT_NOT_INTERACTABLE', reason: 'element is disabled' };
+        }
+        if (storedStableId) {
+            if (!el.stable_id || el.stable_id !== storedStableId) {
+                return { actionable: false, failureCode: 'STALE_REFERENCE', reason: 'element stable_id changed' };
+            }
+        }
+        return { actionable: true };
+    }
     static _computeElementId(platform, deviceId, el, index) {
         const identity = {
             platform,
@@ -120,7 +178,8 @@ export class ToolsInteract {
             platform,
             deviceId,
             bounds,
-            index
+            index,
+            stable_id: el.stable_id ?? null
         });
         return {
             text: el.text ?? null,
@@ -138,6 +197,214 @@ export class ToolsInteract {
             semantic: el.semantic ?? null
         };
     }
+    static _resolveUiChangeScope(tree, scope, target) {
+        const elements = Array.isArray(tree?.elements) ? tree.elements : [];
+        const normalizedScope = scope === 'subtree' ? 'subtree' : 'screen';
+        if (normalizedScope === 'screen') {
+            return {
+                elements,
+                resolution: {
+                    scope: 'screen',
+                    target: null,
+                    resolved: true,
+                    resolvedIndex: null,
+                    resolvedStableId: null,
+                    reason: 'screen scope'
+                }
+            };
+        }
+        const requestedTarget = typeof target === 'string' && target.trim().length > 0 ? target.trim() : null;
+        if (!requestedTarget) {
+            return {
+                elements: [],
+                resolution: {
+                    scope: 'subtree',
+                    target: null,
+                    resolved: false,
+                    resolvedIndex: null,
+                    resolvedStableId: null,
+                    reason: 'subtree scope requires a target element id'
+                },
+                error: {
+                    code: 'INVALID_SCOPE',
+                    message: 'scope=subtree requires a target element_id'
+                }
+            };
+        }
+        const resolved = ToolsInteract._findScopedElement(tree, requestedTarget);
+        if (!resolved) {
+            return {
+                elements: [],
+                resolution: {
+                    scope: 'subtree',
+                    target: requestedTarget,
+                    resolved: false,
+                    resolvedIndex: null,
+                    resolvedStableId: null,
+                    reason: 'target element could not be resolved'
+                },
+                error: {
+                    code: 'ELEMENT_NOT_FOUND',
+                    message: `Target element ${requestedTarget} could not be resolved for subtree scope`
+                }
+            };
+        }
+        const subtreeIndices = ToolsInteract._collectSubtreeIndices(elements, resolved.index);
+        const scopedElements = subtreeIndices.map((index) => elements[index]).filter((element) => !!element);
+        return {
+            elements: scopedElements,
+            resolution: {
+                scope: 'subtree',
+                target: requestedTarget,
+                resolved: true,
+                resolvedIndex: resolved.index,
+                resolvedStableId: resolved.stableId,
+                reason: resolved.reason
+            }
+        };
+    }
+    static _findScopedElement(tree, targetElementId) {
+        const elements = Array.isArray(tree?.elements) ? tree.elements : [];
+        const platform = tree?.device?.platform === 'ios' ? 'ios' : 'android';
+        const deviceId = tree?.device?.id ?? undefined;
+        const normalizedTarget = ToolsInteract._normalize(targetElementId);
+        for (let i = 0; i < elements.length; i++) {
+            const el = elements[i];
+            if (!el)
+                continue;
+            const computedElementId = ToolsInteract._computeElementId(platform, deviceId, el, i);
+            if (computedElementId === targetElementId) {
+                return {
+                    index: i,
+                    stableId: el.stable_id ?? null,
+                    reason: 'element_id_match'
+                };
+            }
+        }
+        for (let i = 0; i < elements.length; i++) {
+            const el = elements[i];
+            if (!el)
+                continue;
+            if (el.stable_id && ToolsInteract._normalize(el.stable_id) === normalizedTarget) {
+                return {
+                    index: i,
+                    stableId: el.stable_id,
+                    reason: 'stable_id_match'
+                };
+            }
+        }
+        const storedContext = ToolsInteract._resolvedUiElements.get(targetElementId);
+        if (storedContext?.stable_id) {
+            const normalizedStoredStableId = ToolsInteract._normalize(storedContext.stable_id);
+            for (let i = 0; i < elements.length; i++) {
+                const el = elements[i];
+                if (!el?.stable_id)
+                    continue;
+                if (ToolsInteract._normalize(el.stable_id) === normalizedStoredStableId) {
+                    return {
+                        index: i,
+                        stableId: el.stable_id,
+                        reason: 'stored_stable_id_match'
+                    };
+                }
+            }
+        }
+        return null;
+    }
+    static _collectSubtreeIndices(elements, rootIndex) {
+        if (!Array.isArray(elements) || rootIndex < 0 || rootIndex >= elements.length)
+            return [];
+        const visited = new Set();
+        const stack = [rootIndex];
+        const result = [];
+        while (stack.length > 0) {
+            const index = stack.pop();
+            if (index === undefined || visited.has(index) || index < 0 || index >= elements.length)
+                continue;
+            visited.add(index);
+            result.push(index);
+            const element = elements[index];
+            if (!element)
+                continue;
+            const directChildren = new Set();
+            if (Array.isArray(element.children)) {
+                for (const childIndex of element.children) {
+                    if (typeof childIndex === 'number' && Number.isInteger(childIndex) && childIndex >= 0 && childIndex < elements.length) {
+                        directChildren.add(childIndex);
+                    }
+                }
+            }
+            for (let i = 0; i < elements.length; i++) {
+                if (ToolsInteract._resolveParentIndex(elements, elements[i]?.parentId) === index) {
+                    directChildren.add(i);
+                }
+            }
+            for (const childIndex of directChildren) {
+                if (!visited.has(childIndex))
+                    stack.push(childIndex);
+            }
+        }
+        return result.sort((left, right) => left - right);
+    }
+    static _changeIdentityForElement(el, index) {
+        const stableId = ToolsInteract._normalize(el.stable_id);
+        if (stableId)
+            return `stable:${stableId}`;
+        return `fallback:${ToolsInteract._hash({
+            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 ?? ''),
+            type: ToolsInteract._normalize(el.type ?? el.class ?? ''),
+            bounds: ToolsInteract._normalizeBounds(el.bounds) ?? [0, 0, 0, 0],
+            index
+        })}`;
+    }
+    static _summarizeUiChangeDelta(initialElements, currentElements) {
+        const buildMap = (elements) => {
+            const map = new Map();
+            for (let i = 0; i < elements.length; i++) {
+                const element = elements[i];
+                if (!element)
+                    continue;
+                const key = ToolsInteract._changeIdentityForElement(element, i);
+                map.set(key, ToolsInteract._hash({
+                    text: ToolsInteract._normalize(element.text ?? element.label ?? element.value ?? ''),
+                    contentDescription: ToolsInteract._normalize(element.contentDescription ?? element.contentDesc ?? element.accessibilityLabel ?? ''),
+                    resourceId: ToolsInteract._normalize(element.resourceId ?? element.resourceID ?? element.id ?? ''),
+                    type: ToolsInteract._normalize(element.type ?? element.class ?? ''),
+                    bounds: ToolsInteract._normalizeBounds(element.bounds) ?? [0, 0, 0, 0],
+                    state: element.state ?? null,
+                    visible: !!element.visible,
+                    enabled: !!element.enabled,
+                    clickable: !!element.clickable
+                }));
+            }
+            return map;
+        };
+        const initialMap = buildMap(initialElements);
+        const currentMap = buildMap(currentElements);
+        let added = 0;
+        let removed = 0;
+        let mutated = 0;
+        for (const [key, value] of currentMap.entries()) {
+            if (!initialMap.has(key)) {
+                added++;
+            }
+            else if (initialMap.get(key) !== value) {
+                mutated++;
+            }
+        }
+        for (const key of initialMap.keys()) {
+            if (!currentMap.has(key))
+                removed++;
+        }
+        return {
+            total_elements: currentElements.length,
+            added_elements: added,
+            removed_elements: removed,
+            mutated_elements: mutated
+        };
+    }
     static _rememberResolvedElement(elementId, context) {
         if (ToolsInteract._resolvedUiElements.has(elementId)) {
             ToolsInteract._resolvedUiElements.delete(elementId);
@@ -384,25 +651,12 @@ export class ToolsInteract {
         let current = chosen;
         let safety = 0;
         while (safety < 20 && current.el && !(current.el.clickable || current.el.focusable || ToolsInteract._isSemanticActionable(current.el)) && current.el.parentId !== undefined && current.el.parentId !== null) {
-            const parentId = current.el.parentId;
-            let parentIndex = null;
-            if (typeof parentId === 'number')
-                parentIndex = parentId;
-            else if (typeof parentId === 'string' && /^\d+$/.test(parentId))
-                parentIndex = Number(parentId);
+            const parentIndex = ToolsInteract._resolveParentIndex(elements, current.el.parentId);
             if (parentIndex !== null && elements[parentIndex]) {
                 current = { el: elements[parentIndex], idx: parentIndex };
                 if (current.el.clickable || current.el.focusable || ToolsInteract._isSemanticActionable(current.el))
                     return current;
             }
-            else if (typeof parentId === 'string') {
-                const foundIndex = elements.findIndex((el) => el.resourceId === parentId || el.id === parentId);
-                if (foundIndex === -1)
-                    break;
-                current = { el: elements[foundIndex], idx: foundIndex };
-                if (current.el.clickable || current.el.focusable || ToolsInteract._isSemanticActionable(current.el))
-                    return current;
-            }
             else {
                 break;
             }
@@ -516,11 +770,9 @@ export class ToolsInteract {
             return ToolsInteract._actionFailure(actionType, selector, null, 'STALE_REFERENCE', true, fingerprintBefore);
         }
         const resolvedTarget = ToolsInteract._resolvedTargetFromElement(resolved.elementId, currentMatch.el, currentMatch.index);
-        if (!ToolsInteract._isVisibleElement(currentMatch.el)) {
-            return ToolsInteract._actionFailure(actionType, selector, resolvedTarget, 'ELEMENT_NOT_INTERACTABLE', true, fingerprintBefore);
-        }
-        if (currentMatch.el.enabled === false) {
-            return ToolsInteract._actionFailure(actionType, selector, resolvedTarget, 'ELEMENT_NOT_INTERACTABLE', true, fingerprintBefore);
+        const tapActionability = ToolsInteract._isTapActionable(currentMatch.el, resolved.stable_id, resolved.platform);
+        if (!tapActionability.actionable) {
+            return ToolsInteract._actionFailure(actionType, selector, resolvedTarget, tapActionability.failureCode ?? 'ELEMENT_NOT_INTERACTABLE', true, fingerprintBefore);
         }
         const bounds = ToolsInteract._normalizeBounds(currentMatch.el.bounds) ?? resolved.bounds;
         if (!bounds || bounds[2] <= bounds[0] || bounds[3] <= bounds[1]) {
@@ -553,6 +805,7 @@ export class ToolsInteract {
         const sourcePlatform = platform || 'android';
         let resolvedPlatform = sourcePlatform;
         let resolvedDeviceId = deviceId;
+        const storedResolvedTarget = element_id ? ToolsInteract._resolvedUiElements.get(element_id) ?? null : null;
         const fingerprintBefore = await ToolsInteract._captureFingerprint(resolvedPlatform, resolvedDeviceId);
         let semanticFallbackElement = null;
         const traceSteps = [];
@@ -758,6 +1011,10 @@ export class ToolsInteract {
             resolvedTarget = resolved.resolvedTarget;
             const currentEl = resolved.match.el;
             cachedResolvedMatch = resolved.match;
+            const adjustableActionability = ToolsInteract._isAdjustableActionable(currentEl, storedResolvedTarget?.stable_id);
+            if (!adjustableActionability.actionable) {
+                return buildFailure(adjustableActionability.failureCode ?? 'ELEMENT_NOT_INTERACTABLE', adjustableActionability.reason ?? 'adjustable control is not actionable', resolvedTarget, currentDevice, lastObservedState, attemptCount, lastAdjustmentMode, true);
+            }
             const bounds = ToolsInteract._normalizeBounds(currentEl.bounds);
             const valueRange = currentEl.state?.value_range ?? null;
             const currentValue = ToolsInteract._readNumericControlValue(currentEl, property);
@@ -1711,24 +1968,65 @@ export class ToolsInteract {
             }
         };
     }
-    static async waitForUIChangeHandler({ platform, deviceId, timeout_ms = 60000, stability_window_ms = 300, expected_change }) {
+    static async waitForUIChangeHandler({ platform, deviceId, timeout_ms = 60000, stability_window_ms = 300, expected_change, scope = 'screen', target = null }) {
         const start = Date.now();
         const pollIntervalMs = 300;
         const stabilityWindow = Math.max(0, typeof stability_window_ms === 'number' ? stability_window_ms : 300);
         let baseline = null;
+        let baselineScope = null;
         let lastObservedRevision = null;
         let lastLoadingState = null;
+        let lastSnapshotFreshnessMs = null;
         let candidateSignatures = null;
         let candidateObservedChange = null;
         let candidateSinceMs = null;
+        let lastChangeSummary = null;
+        let lastScopeResolution = {
+            scope: scope === 'subtree' ? 'subtree' : 'screen',
+            target: target && typeof target === 'string' ? target : null,
+            resolved: scope !== 'subtree',
+            resolvedIndex: null,
+            resolvedStableId: null,
+            reason: scope === 'subtree' ? 'target not resolved yet' : 'screen scope'
+        };
         while (Date.now() - start < timeout_ms) {
             try {
                 const tree = await ToolsObserve.getUITreeHandler({ platform, deviceId });
-                const signatures = ToolsInteract._buildUiChangeSignatures(tree);
+                const scopedTree = ToolsInteract._resolveUiChangeScope(tree, scope, target);
+                if (scopedTree.error) {
+                    lastScopeResolution = scopedTree.resolution;
+                    return {
+                        success: false,
+                        observed_change: null,
+                        snapshot_revision: typeof tree?.snapshot_revision === 'number' ? tree.snapshot_revision : lastObservedRevision ?? undefined,
+                        snapshot_freshness_ms: typeof tree?.captured_at_ms === 'number' ? Math.max(0, Date.now() - tree.captured_at_ms) : lastSnapshotFreshnessMs ?? null,
+                        timeout: true,
+                        elapsed_ms: Date.now() - start,
+                        expected_change,
+                        loading_state: tree?.loading_state ?? lastLoadingState ?? null,
+                        scope: scopedTree.resolution.scope,
+                        target: scopedTree.resolution.target,
+                        stability_state: 'transient',
+                        change_summary: lastChangeSummary,
+                        reason: scopedTree.error.message,
+                        error: scopedTree.error
+                    };
+                }
+                const scopedElements = scopedTree.elements;
+                const scopedSignatureTree = {
+                    ...tree,
+                    elements: scopedElements
+                };
+                const signatures = ToolsInteract._buildUiChangeSignatures(scopedSignatureTree);
                 lastObservedRevision = typeof tree?.snapshot_revision === 'number' ? tree.snapshot_revision : lastObservedRevision;
                 lastLoadingState = tree?.loading_state ?? lastLoadingState;
+                lastSnapshotFreshnessMs = typeof tree?.captured_at_ms === 'number' ? Math.max(0, Date.now() - tree.captured_at_ms) : lastSnapshotFreshnessMs;
+                lastChangeSummary = baseline ? ToolsInteract._summarizeUiChangeDelta((baselineScope?.elements ?? []), scopedElements) : lastChangeSummary;
+                lastScopeResolution = scopedTree.resolution;
+                baselineScope = baselineScope ?? scopedTree;
                 if (!baseline) {
                     baseline = signatures;
+                    baselineScope = scopedTree;
                 }
                 else {
                     const observedChange = ToolsInteract._matchesUiChange(expected_change, baseline, signatures);
@@ -1744,10 +2042,15 @@ export class ToolsInteract {
                                 success: true,
                                 observed_change: candidateObservedChange ?? observedChange,
                                 snapshot_revision: lastObservedRevision ?? undefined,
+                                snapshot_freshness_ms: lastSnapshotFreshnessMs ?? null,
                                 timeout: false,
                                 elapsed_ms: Date.now() - start,
                                 expected_change,
                                 loading_state: lastLoadingState ?? null,
+                                scope: lastScopeResolution.scope,
+                                target: lastScopeResolution.target,
+                                stability_state: 'stable',
+                                change_summary: lastChangeSummary,
                                 reason: 'UI change observed'
                             };
                         }
@@ -1768,10 +2071,15 @@ export class ToolsInteract {
             success: false,
             observed_change: null,
             snapshot_revision: lastObservedRevision ?? undefined,
+            snapshot_freshness_ms: lastSnapshotFreshnessMs ?? null,
             timeout: true,
             elapsed_ms: Date.now() - start,
             expected_change,
             loading_state: lastLoadingState ?? null,
+            scope: lastScopeResolution.scope,
+            target: lastScopeResolution.target,
+            stability_state: 'transient',
+            change_summary: lastChangeSummary,
             reason: 'timeout'
         };
     }

package/dist/observe/index.js

@@ -325,6 +325,7 @@ export class ToolsObserve {
         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.snapshot_delta = raw.ui_tree?.snapshot_delta ?? snapshotMetadata.snapshot_delta ?? null;
         raw.loading_state = raw.ui_tree?.loading_state ?? snapshotMetadata.loading_state;
         const semantic = deriveSnapshotSemantic(raw);
         return semantic ? { raw, semantic } : { raw };

package/dist/observe/snapshot-metadata.js

@@ -30,6 +30,58 @@ function stableElementSignature(element) {
         bounds: normalizeBounds(element.bounds)
     };
 }
+function stableElementIdentity(element, index) {
+    const stableId = normalize(element.stable_id);
+    if (stableId)
+        return `stable:${stableId}`;
+    return `fallback:${crypto.createHash('sha1').update(JSON.stringify({
+        text: normalize(element.text),
+        contentDescription: normalize(element.contentDescription),
+        resourceId: normalize(element.resourceId),
+        type: normalize(element.type),
+        bounds: normalizeBounds(element.bounds),
+        index
+    })).digest('hex')}`;
+}
+function buildElementSignatures(tree) {
+    const signatures = new Map();
+    const elements = Array.isArray(tree?.elements) ? tree.elements : [];
+    for (let index = 0; index < elements.length; index++) {
+        const element = elements[index];
+        if (!element)
+            continue;
+        const identity = stableElementIdentity(element, index);
+        signatures.set(identity, crypto.createHash('sha1').update(JSON.stringify(stableElementSignature(element))).digest('hex'));
+    }
+    return signatures;
+}
+function summarizeSnapshotDelta(previous, currentElements) {
+    if (!previous)
+        return null;
+    let added = 0;
+    let removed = 0;
+    let mutated = 0;
+    for (const [identity, signature] of currentElements.entries()) {
+        const previousSignature = previous.elementSignatures.get(identity);
+        if (previousSignature === undefined) {
+            added++;
+        }
+        else if (previousSignature !== signature) {
+            mutated++;
+        }
+    }
+    for (const identity of previous.elementSignatures.keys()) {
+        if (!currentElements.has(identity))
+            removed++;
+    }
+    return {
+        previous_snapshot_revision: previous.revision,
+        added_elements: added,
+        removed_elements: removed,
+        mutated_elements: mutated,
+        total_elements: currentElements.size
+    };
+}
 export function computeSnapshotSignature(tree) {
     if (!tree || tree.error)
         return null;
@@ -67,6 +119,10 @@ export function detectLoadingState(tree, source) {
 export function deriveSnapshotMetadata(deviceKey, tree, source, signatureOverride) {
     const signature = signatureOverride ?? computeSnapshotSignature(tree);
     const previous = snapshotStateByDevice.get(deviceKey);
+    const hasValidTree = !!tree && !tree.error;
+    const currentElementSignatures = hasValidTree
+        ? buildElementSignatures(tree)
+        : previous?.elementSignatures ?? new Map();
     let revision = 1;
     if (previous) {
         if (signature === null) {
@@ -76,10 +132,15 @@ export function deriveSnapshotMetadata(deviceKey, tree, source, signatureOverrid
             revision = previous.signature === signature ? previous.revision : previous.revision + 1;
         }
     }
-    snapshotStateByDevice.set(deviceKey, { revision, signature });
+    snapshotStateByDevice.set(deviceKey, {
+        revision,
+        signature,
+        elementSignatures: currentElementSignatures
+    });
     return {
         snapshot_revision: revision,
         captured_at_ms: Date.now(),
+        snapshot_delta: hasValidTree ? summarizeSnapshotDelta(previous, currentElementSignatures) : null,
         loading_state: detectLoadingState(tree, source)
     };
 }

package/dist/server/tool-definitions.js

@@ -244,7 +244,7 @@ Failure Handling:
     },
     {
         name: 'capture_debug_snapshot',
-        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.',
+        description: 'Capture a complete debug snapshot (raw observation layer plus optional derived semantic layer). Returns structured JSON with snapshot_revision, captured_at_ms, snapshot_delta, and loading_state when detectable.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -295,7 +295,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 with snapshot metadata when available.',
+        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 and incremental delta signals when available.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -376,11 +376,14 @@ Inputs:
 - expected_change (optional): hierarchy_diff, text_change, or state_change
 - timeout_ms (optional)
 - stability_window_ms (optional)
+- scope (optional): screen or subtree
+- target (optional): element_id when scope=subtree
 
 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.
+- Scoped waits return scope-aware stability metadata and a lightweight change summary.
 
 Failure Handling:
 - TIMEOUT means the UI did not change in a stable way within the allotted time.`,
@@ -390,6 +393,8 @@ Failure Handling:
                 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' },
+                scope: { type: 'string', enum: ['screen', 'subtree'], default: 'screen', description: 'Synchronization scope for the wait' },
+                target: { type: 'string', description: 'Target element_id when scope is subtree' },
                 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 300)', default: 300 }
             }

package/dist/server/tool-handlers.js

@@ -268,7 +268,9 @@ async function handleWaitForUIChange(args) {
     const timeout_ms = getNumberArg(args, 'timeout_ms') ?? 60000;
     const stability_window_ms = getNumberArg(args, 'stability_window_ms') ?? 300;
     const expected_change = getStringArg(args, 'expected_change');
-    const res = await ToolsInteract.waitForUIChangeHandler({ platform, deviceId, timeout_ms, stability_window_ms, expected_change });
+    const scope = getStringArg(args, 'scope');
+    const target = getStringArg(args, 'target');
+    const res = await ToolsInteract.waitForUIChangeHandler({ platform, deviceId, timeout_ms, stability_window_ms, expected_change, scope, target });
     return wrapResponse(res);
 }
 async function handleFindElement(args) {

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.30.0'
+    version: '0.30.1'
 };
 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.30.1]
+- Synced the server-reported version in `src/server-core.ts` with `package.json` so contract checks pass.
+- Completed the RFC 013 wait/synchronization implementation, including scoped waits and freshness metadata.
+- Completed the RFC 014 actionability implementation for taps and adjustable controls.
+- Added regression coverage for subtree collection, scoped waits, snapshot deltas, and stale actionability checks.
+
 ## [0.30.0]
 - Folded RFC 013 synchronization semantics into the main spec and aligned the interact docs with the shipped `wait_for_ui_change` behavior.
 - Updated `wait_for_ui_change` to use a 300ms stabilization default and to reset stabilization on new in-place mutations.