mobile-debug-mcp 0.30.0 → 0.30.2

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);
@@ -261,13 +528,214 @@ export class ToolsInteract {
         const stateValue = el.state[property];
         if (typeof stateValue === 'number' && Number.isFinite(stateValue))
             return stateValue;
+        const parsedStateValue = ToolsInteract._parseNumericControlValue(stateValue);
+        if (parsedStateValue !== null)
+            return parsedStateValue;
         if (property === 'value' || property === 'raw_value') {
             const fallback = el.state.raw_value ?? el.state.value;
             if (typeof fallback === 'number' && Number.isFinite(fallback))
                 return fallback;
+            return ToolsInteract._parseNumericControlValue(fallback);
+        }
+        return null;
+    }
+    static _parseNumericControlValue(value) {
+        if (typeof value === 'number' && Number.isFinite(value))
+            return value;
+        if (typeof value !== 'string')
+            return null;
+        const trimmed = value.trim();
+        if (!trimmed)
+            return null;
+        const percent = trimmed.match(/^([-+]?\d+(?:\.\d+)?)\s*%$/);
+        if (percent)
+            return Number(percent[1]);
+        const fraction = trimmed.match(/^([-+]?\d+(?:\.\d+)?)\s+of\s+[-+]?\d+(?:\.\d+)?$/i);
+        if (fraction)
+            return Number(fraction[1]);
+        const plain = Number(trimmed);
+        if (Number.isFinite(plain))
+            return plain;
+        const trailing = trimmed.match(/,\s*([-+]?\d+(?:\.\d+)?)$/);
+        if (trailing)
+            return Number(trailing[1]);
+        return null;
+    }
+    static _readNumericControlRange(el) {
+        const min = typeof el?.state?.value_range?.min === 'number' ? el.state.value_range.min : null;
+        const max = typeof el?.state?.value_range?.max === 'number' ? el.state.value_range.max : null;
+        if (min !== null && max !== null && Number.isFinite(min) && Number.isFinite(max) && max > min) {
+            return { min, max };
+        }
+        const value = el?.state?.value ?? el?.state?.raw_value;
+        if (typeof value === 'string') {
+            const fraction = value.trim().match(/^[-+]?\d+(?:\.\d+)?\s+of\s+([-+]?\d+(?:\.\d+)?)$/i);
+            if (fraction) {
+                const parsedMax = Number(fraction[1]);
+                if (Number.isFinite(parsedMax) && parsedMax > 0)
+                    return { min: 0, max: parsedMax };
+            }
         }
         return null;
     }
+    static _readControlStep(el) {
+        const candidates = [
+            el?.state?.step,
+            el?.state?.value_range?.step
+        ];
+        for (const candidate of candidates) {
+            if (typeof candidate === 'number' && Number.isFinite(candidate) && candidate > 0)
+                return candidate;
+        }
+        return null;
+    }
+    static _quantizeTargetValue(targetValue, min, max, step) {
+        if (!step)
+            return targetValue;
+        const quantized = min + (Math.round((targetValue - min) / step) * step);
+        const bounded = Math.max(min, Math.min(max, quantized));
+        const precision = ToolsInteract._decimalPrecisionForStep(step);
+        return Number(bounded.toFixed(precision));
+    }
+    static _decimalPrecisionForStep(step) {
+        const normalized = String(step).toLowerCase();
+        const [coefficient, exponentPart] = normalized.split('e');
+        const coefficientDecimals = coefficient.includes('.')
+            ? coefficient.split('.')[1]?.length ?? 0
+            : 0;
+        const exponent = exponentPart !== undefined ? Number(exponentPart) : 0;
+        const precision = exponent < 0
+            ? coefficientDecimals + Math.abs(exponent)
+            : Math.max(0, coefficientDecimals - exponent);
+        return Math.max(0, Math.min(12, precision));
+    }
+    static _defaultAdjustTolerance(range, step) {
+        if (step)
+            return 0;
+        if (!range)
+            return 0;
+        return Math.max(0, 0.01 * Math.abs(range.max - range.min));
+    }
+    static _runtimeActionSet(el) {
+        const values = [
+            ...(Array.isArray(el?.actions) ? el.actions : []),
+            ...(Array.isArray(el?.accessibilityActions) ? el.accessibilityActions : []),
+            ...(Array.isArray(el?.runtimeActions) ? el.runtimeActions : []),
+            ...(Array.isArray(el?.platformActions) ? el.platformActions : [])
+        ];
+        return new Set(values.map((value) => ToolsInteract._normalize(value)).filter(Boolean));
+    }
+    static _hasDirectAdjustmentAction(el) {
+        const actions = ToolsInteract._runtimeActionSet(el);
+        return [
+            'action_set_progress',
+            'set_progress',
+            'setprogress',
+            'semanticsactions.setprogress',
+            'set_value',
+            'setvalue',
+            'direct_set_value'
+        ].some((action) => actions.has(action));
+    }
+    static _adjustmentDirections(el) {
+        const actions = ToolsInteract._runtimeActionSet(el);
+        return {
+            increment: ['increment', 'accessibility_increment', 'action_increment'].some((action) => actions.has(action)),
+            decrement: ['decrement', 'accessibility_decrement', 'action_decrement'].some((action) => actions.has(action))
+        };
+    }
+    static _textFromElement(el) {
+        return String(el?.text ?? el?.contentDescription ?? el?.contentDesc ?? el?.accessibilityLabel ?? el?.value ?? '').trim();
+    }
+    static _parseLeadingNumber(text) {
+        const match = text.trim().match(/^([-+]?\d+(?:\.\d+)?)(?:\s*[a-zA-Z%]+)?$/);
+        if (!match)
+            return null;
+        const value = Number(match[1]);
+        return Number.isFinite(value) ? value : null;
+    }
+    static _inferLabeledSliderState(elements, track) {
+        const trackBounds = ToolsInteract._normalizeBounds(track?.bounds);
+        if (!track || !trackBounds)
+            return null;
+        const type = ToolsInteract._normalize(track.type ?? track.class ?? '');
+        const role = ToolsInteract._normalize(track.role ?? '');
+        const width = trackBounds[2] - trackBounds[0];
+        const height = trackBounds[3] - trackBounds[1];
+        const wideTrackLike = width >= 240 && height <= 220;
+        const knownTrackLike = /slider|seekbar|range/.test(type) || /slider|range/.test(role);
+        if (!wideTrackLike && !knownTrackLike)
+            return null;
+        const trackTop = trackBounds[1];
+        const trackBottom = trackBounds[3];
+        const trackCenterX = (trackBounds[0] + trackBounds[2]) / 2;
+        const labels = elements
+            .map((el, index) => {
+            const bounds = ToolsInteract._normalizeBounds(el.bounds);
+            const text = ToolsInteract._textFromElement(el);
+            const value = ToolsInteract._parseLeadingNumber(text);
+            return bounds && text && value !== null
+                ? {
+                    index,
+                    el,
+                    text,
+                    value,
+                    bounds,
+                    centerX: (bounds[0] + bounds[2]) / 2,
+                    centerY: (bounds[1] + bounds[3]) / 2,
+                    hasUnit: /[a-zA-Z%]/.test(text)
+                }
+                : null;
+        })
+            .filter((label) => !!label);
+        const rangeLabels = labels
+            .filter((label) => {
+            const verticallyNearTrack = label.centerY >= trackTop - 520 && label.centerY <= trackBottom + 260;
+            const horizontallyNearTrack = label.centerX >= trackBounds[0] - 120 && label.centerX <= trackBounds[2] + 120;
+            return verticallyNearTrack && horizontallyNearTrack && label.hasUnit;
+        })
+            .sort((a, b) => a.centerX - b.centerX);
+        if (rangeLabels.length < 2)
+            return null;
+        const minLabel = rangeLabels[0];
+        const maxLabel = rangeLabels[rangeLabels.length - 1];
+        if (!minLabel || !maxLabel || maxLabel.value <= minLabel.value)
+            return null;
+        const currentCandidates = labels
+            .filter((label) => {
+            if (label.index === minLabel.index || label.index === maxLabel.index)
+                return false;
+            if (label.value < minLabel.value || label.value > maxLabel.value)
+                return false;
+            if (label.centerY < trackTop - 950 || label.centerY > minLabel.centerY - 20)
+                return false;
+            return label.centerX >= trackCenterX - 80;
+        })
+            .sort((a, b) => {
+            const yDistance = Math.abs((trackTop - 420) - a.centerY) - Math.abs((trackTop - 420) - b.centerY);
+            if (yDistance !== 0)
+                return yDistance;
+            return b.centerX - a.centerX;
+        });
+        const currentLabel = currentCandidates[0];
+        if (!currentLabel)
+            return null;
+        const candidateBelowRangeLabels = minLabel.centerY < trackTop && maxLabel.centerY < trackTop;
+        const labelDerivedBounds = [
+            Math.min(minLabel.bounds[0], trackBounds[0]),
+            Math.max(currentLabel.bounds[3] + 12, Math.min(minLabel.bounds[1], maxLabel.bounds[1]) - 160),
+            Math.max(maxLabel.bounds[2], trackBounds[2]),
+            Math.max(currentLabel.bounds[3] + 80, Math.min(minLabel.bounds[1], maxLabel.bounds[1]) - 32)
+        ];
+        return {
+            current: currentLabel.value,
+            min: minLabel.value,
+            max: maxLabel.value,
+            value_range: { min: minLabel.value, max: maxLabel.value },
+            touch_bounds: candidateBelowRangeLabels ? labelDerivedBounds : trackBounds,
+            source: 'nearby_labels'
+        };
+    }
     static _buildControlPoint(bounds, ratio, axis) {
         const clampedRatio = Math.max(0, Math.min(1, ratio));
         const [left, top, right, bottom] = bounds;
@@ -384,25 +852,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 +971,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]) {
@@ -545,14 +998,17 @@ export class ToolsInteract {
             sourceModule: 'interact'
         });
     }
-    static async adjustControlHandler({ selector, element_id, property = 'value', targetValue, tolerance = 0, maxAttempts = 3, platform, deviceId }) {
+    static async adjustControlHandler({ selector, element_id, property = 'value', targetValue, tolerance, maxAttempts, platform, deviceId }) {
         const actionType = 'adjust_control';
         const targetSelector = selector ?? (element_id ? { elementId: element_id } : null);
-        const normalizedTolerance = Number.isFinite(tolerance) ? Math.max(0, tolerance) : 0;
-        const attemptsLimit = Math.max(1, Math.floor(Number(maxAttempts) || 1));
+        const requestedTolerance = typeof tolerance === 'number' && Number.isFinite(tolerance) ? Math.max(0, tolerance) : null;
+        const attemptsLimit = maxAttempts === undefined || maxAttempts === null
+            ? 5
+            : Math.max(1, Math.floor(Number(maxAttempts) || 1));
         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 = [];
@@ -582,6 +1038,7 @@ export class ToolsInteract {
                     retry_depth: attempts
                 });
             }
+            const responseTolerance = requestedTolerance ?? 0;
             const base = buildActionExecutionResult({
                 actionType,
                 sourceModule: 'interact',
@@ -594,7 +1051,7 @@ export class ToolsInteract {
                 failure: { failureCode, retryable },
                 details: {
                     target_value: targetValue,
-                    tolerance: normalizedTolerance,
+                    tolerance: responseTolerance,
                     property,
                     attempts,
                     adjustment_mode: adjustmentMode,
@@ -610,7 +1067,7 @@ export class ToolsInteract {
                 target_state: {
                     property,
                     target_value: targetValue,
-                    tolerance: normalizedTolerance
+                    tolerance: responseTolerance
                 },
                 actual_state: actualState,
                 within_tolerance: false,
@@ -702,8 +1159,8 @@ export class ToolsInteract {
             }
             return null;
         };
-        if (!selector && !element_id) {
-            return buildFailure('ELEMENT_NOT_FOUND', 'selector or element_id is required', null, undefined, null, 0, 'gesture', false);
+        if ((!selector && !element_id) || (selector && element_id)) {
+            return buildFailure('ELEMENT_NOT_FOUND', 'exactly one of selector or element_id is required', null, undefined, null, 0, 'gesture', false);
         }
         if (selector && !element_id) {
             const waitResult = await ToolsInteract.waitForUIHandler({
@@ -742,7 +1199,8 @@ export class ToolsInteract {
         let currentDevice = undefined;
         let attemptCount = 0;
         let cachedResolvedMatch = null;
-        for (let attempt = 0; attempt < attemptsLimit; attempt++) {
+        let coordinateTapsAwaitingFreshGesture = false;
+        adjustmentAttempts: for (let attempt = 0; attempt < attemptsLimit && attemptCount < attemptsLimit; attempt++) {
             const resolved = cachedResolvedMatch
                 ? {
                     tree: null,
@@ -758,11 +1216,33 @@ export class ToolsInteract {
             resolvedTarget = resolved.resolvedTarget;
             const currentEl = resolved.match.el;
             cachedResolvedMatch = resolved.match;
-            const bounds = ToolsInteract._normalizeBounds(currentEl.bounds);
-            const valueRange = currentEl.state?.value_range ?? null;
-            const currentValue = ToolsInteract._readNumericControlValue(currentEl, property);
+            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 elementsForInference = Array.isArray(resolved.tree?.elements)
+                ? resolved.tree.elements
+                : cachedResolvedMatch
+                    ? [cachedResolvedMatch.el]
+                    : [currentEl];
+            const inferredSliderState = ToolsInteract._inferLabeledSliderState(elementsForInference, currentEl);
+            const nativeBounds = ToolsInteract._normalizeBounds(currentEl.bounds);
+            const bounds = inferredSliderState?.touch_bounds ?? nativeBounds;
+            const valueRange = ToolsInteract._readNumericControlRange(currentEl) ?? inferredSliderState?.value_range ?? null;
+            const step = ToolsInteract._readControlStep(currentEl);
+            const normalizedTargetValue = valueRange
+                ? ToolsInteract._quantizeTargetValue(targetValue, valueRange.min, valueRange.max, step)
+                : targetValue;
+            const effectiveTolerance = requestedTolerance ?? ToolsInteract._defaultAdjustTolerance(valueRange, step);
+            const currentValue = ToolsInteract._readNumericControlValue(currentEl, property) ?? inferredSliderState?.current ?? null;
             const actualState = currentValue !== null
-                ? { property, value: currentValue, raw_value: typeof currentEl.state?.raw_value === 'number' ? currentEl.state.raw_value : undefined }
+                ? {
+                    property,
+                    value: currentValue,
+                    raw_value: typeof currentEl.state?.raw_value === 'number'
+                        ? currentEl.state.raw_value
+                        : inferredSliderState?.current
+                }
                 : null;
             lastObservedState = actualState;
             if (!traceSteps.some((step) => step.stage === 'resolve')) {
@@ -775,10 +1255,20 @@ export class ToolsInteract {
             if (property !== 'value' && property !== 'raw_value') {
                 return buildFailure('ELEMENT_NOT_INTERACTABLE', 'adjust_control currently supports numeric value and raw_value properties only', resolvedTarget, currentDevice, actualState, attemptCount, lastAdjustmentMode, false);
             }
-            if (currentValue !== null && Math.abs(currentValue - targetValue) <= normalizedTolerance) {
+            const isAdjustableControl = ToolsInteract._isAdjustableControl(currentEl) || !!inferredSliderState;
+            if (!isAdjustableControl) {
+                return buildFailure('ELEMENT_NOT_INTERACTABLE', 'target is not an adjustable control', resolvedTarget, currentDevice, actualState, attemptCount, lastAdjustmentMode, false);
+            }
+            if (currentValue === null) {
+                return buildFailure('UNKNOWN', 'current numeric value is unavailable', resolvedTarget, currentDevice, actualState, attemptCount, lastAdjustmentMode, false);
+            }
+            if (valueRange && (targetValue < valueRange.min || targetValue > valueRange.max)) {
+                return buildFailure('CONTROL_CONVERGENCE_FAILED', `targetValue ${targetValue} is outside the control range ${valueRange.min}..${valueRange.max}`, resolvedTarget, currentDevice, actualState, attemptCount, lastAdjustmentMode, false);
+            }
+            if (currentValue !== null && Math.abs(currentValue - normalizedTargetValue) <= effectiveTolerance) {
                 recordTraceStep('verify', 'success', {
                     property,
-                    target_value: targetValue,
+                    target_value: normalizedTargetValue,
                     actual_state: actualState,
                     reason: 'control already within tolerance'
                 });
@@ -793,8 +1283,8 @@ export class ToolsInteract {
                     uiFingerprintBefore: fingerprintBefore,
                     uiFingerprintAfter,
                     details: {
-                        target_value: targetValue,
-                        tolerance: normalizedTolerance,
+                        target_value: normalizedTargetValue,
+                        tolerance: effectiveTolerance,
                         property,
                         attempts: attemptCount,
                         adjustment_mode: 'semantic',
@@ -809,8 +1299,8 @@ export class ToolsInteract {
                     ...base,
                     target_state: {
                         property,
-                        target_value: targetValue,
-                        tolerance: normalizedTolerance
+                        target_value: normalizedTargetValue,
+                        tolerance: effectiveTolerance
                     },
                     actual_state: actualState,
                     within_tolerance: true,
@@ -819,40 +1309,40 @@ export class ToolsInteract {
                     adjustment_mode: 'semantic'
                 };
             }
-            if (!ToolsInteract._isAdjustableControl(currentEl)) {
-                return buildFailure('ELEMENT_NOT_INTERACTABLE', 'target is not an adjustable control', resolvedTarget, currentDevice, actualState, attemptCount, lastAdjustmentMode, false);
-            }
             if (!bounds) {
                 return buildFailure('ELEMENT_NOT_INTERACTABLE', 'adjustable control has no bounds', resolvedTarget, currentDevice, actualState, attemptCount, lastAdjustmentMode, false);
             }
-            const min = typeof valueRange?.min === 'number' ? valueRange.min : null;
-            const max = typeof valueRange?.max === 'number' ? valueRange.max : null;
-            if (min === null || max === null || !Number.isFinite(min) || !Number.isFinite(max) || max <= min) {
-                return buildFailure('ELEMENT_NOT_INTERACTABLE', 'value_range unavailable', resolvedTarget, currentDevice, actualState, attemptCount, lastAdjustmentMode, false);
-            }
-            if (targetValue < min || targetValue > max) {
-                return buildFailure('UNKNOWN', `targetValue ${targetValue} is outside the control range ${min}..${max}`, resolvedTarget, currentDevice, actualState, attemptCount, lastAdjustmentMode, false);
-            }
-            const axis = ToolsInteract._controlAxis(currentEl, bounds);
-            const targetPoint = ToolsInteract._buildConservativeControlPoint(bounds, targetValue, currentValue, min, max, axis);
-            const currentPoint = currentValue !== null
-                ? ToolsInteract._buildControlPoint(bounds, (currentValue - min) / (max - min), axis)
-                : ToolsInteract._buildControlPoint(bounds, 0.5, axis);
-            const probePoints = ToolsInteract._buildAdjustmentProbePoints(bounds, targetValue, currentValue, min, max, axis);
             const runVerification = async () => {
+                if (inferredSliderState) {
+                    const tree = await ToolsObserve.getUITreeHandler({ platform: resolvedPlatform, deviceId: resolvedDeviceId });
+                    const elements = Array.isArray(tree?.elements) ? tree.elements : [];
+                    const refreshed = ToolsInteract._inferLabeledSliderState(elements, currentEl);
+                    const observedValue = refreshed?.current ?? null;
+                    const observedState = observedValue !== null
+                        ? { property, value: observedValue, raw_value: observedValue }
+                        : actualState;
+                    return {
+                        verification: {
+                            success: observedValue !== null && Math.abs(observedValue - normalizedTargetValue) <= effectiveTolerance,
+                            observed_state: observedState,
+                            reason: observedValue !== null
+                                ? 'visible labeled value read from nearby slider labels'
+                                : 'visible labeled value unavailable'
+                        },
+                        observedState,
+                        withinTolerance: observedValue !== null && Math.abs(observedValue - normalizedTargetValue) <= effectiveTolerance
+                    };
+                }
                 const verification = await ToolsInteract.expectStateHandler({
                     element_id: resolvedTarget?.elementId ?? element_id,
                     selector: selector ?? undefined,
                     property,
-                    expected: targetValue,
+                    expected: normalizedTargetValue,
                     platform: resolvedPlatform,
                     deviceId: resolvedDeviceId
                 });
-                const observedValue = typeof verification?.observed_state?.value === 'number'
-                    ? verification.observed_state.value
-                    : typeof verification?.observed_state?.raw_value === 'number'
-                        ? verification.observed_state.raw_value
-                        : null;
+                const observedValue = ToolsInteract._parseNumericControlValue(verification?.observed_state?.value) ??
+                    ToolsInteract._parseNumericControlValue(verification?.observed_state?.raw_value);
                 const observedState = observedValue !== null
                     ? {
                         property,
@@ -863,88 +1353,266 @@ export class ToolsInteract {
                 return {
                     verification,
                     observedState,
-                    withinTolerance: observedValue !== null && Math.abs(observedValue - targetValue) <= normalizedTolerance
+                    withinTolerance: observedValue !== null && Math.abs(observedValue - normalizedTargetValue) <= effectiveTolerance
                 };
             };
             let actionDevice = currentDevice;
             let observedState = actualState;
             let verification = null;
             let verificationResult = { verification: null, observedState: actualState, withinTolerance: false };
-            for (let i = 0; i < probePoints.length; i++) {
-                const probePoint = probePoints[i];
-                lastAdjustmentMode = 'coordinate';
-                recordTraceStep('execute', 'retry', {
-                    attempt: attemptCount + 1,
-                    mode: 'coordinate',
-                    point: probePoint
-                });
-                const actionResult = await ToolsInteract.tapHandler({
-                    platform: resolvedPlatform,
-                    x: probePoint.x,
-                    y: probePoint.y,
-                    deviceId: resolvedDeviceId
-                });
-                attemptCount++;
-                actionDevice = actionResult.device ?? actionDevice;
-                if (!actionResult.success) {
+            const directActionSupported = ToolsInteract._hasDirectAdjustmentAction(currentEl);
+            if (directActionSupported && attemptCount < attemptsLimit) {
+                const { interact, resolved: actionResolved } = await ToolsInteract.getInteractionService(resolvedPlatform, resolvedDeviceId);
+                if (typeof interact.setAdjustableValue === 'function') {
+                    lastAdjustmentMode = 'semantic';
                     recordTraceStep('execute', 'retry', {
-                        attempt: attemptCount,
-                        mode: 'coordinate',
-                        point: probePoint,
-                        success: false
+                        attempt: attemptCount + 1,
+                        mode: 'semantic',
+                        strategy: 'direct_set_value',
+                        target_value: normalizedTargetValue
                     });
-                    continue;
-                }
-                verificationResult = await runVerification();
-                observedState = verificationResult.observedState;
-                lastObservedState = observedState;
-                recordTraceStep('verify', verificationResult.withinTolerance ? 'success' : 'retry', {
-                    attempt: attemptCount,
-                    property,
-                    target_value: targetValue,
-                    actual_state: observedState,
-                    reason: verificationResult.verification?.reason ?? 'control did not converge yet'
-                });
-                if (verificationResult.withinTolerance) {
-                    const uiFingerprintAfter = await ToolsInteract._captureFingerprint(resolvedPlatform, resolvedDeviceId);
-                    const base = buildActionExecutionResult({
-                        actionType,
-                        sourceModule: 'interact',
-                        device: actionDevice ?? currentDevice,
-                        selector: targetSelector,
-                        resolved: resolvedTarget,
-                        success: true,
-                        uiFingerprintBefore: fingerprintBefore,
-                        uiFingerprintAfter,
-                        details: {
-                            target_value: targetValue,
-                            tolerance: normalizedTolerance,
+                    const actionResult = await interact.setAdjustableValue({
+                        deviceId: actionResolved.id,
+                        target: resolvedTarget,
+                        property,
+                        value: normalizedTargetValue
+                    });
+                    attemptCount++;
+                    actionDevice = actionResult?.device ?? actionDevice;
+                    if (actionResult?.success !== false) {
+                        verificationResult = await runVerification();
+                        observedState = verificationResult.observedState;
+                        lastObservedState = observedState;
+                        recordTraceStep('verify', verificationResult.withinTolerance ? 'success' : 'retry', {
+                            attempt: attemptCount,
                             property,
-                            attempts: attemptCount,
-                            adjustment_mode: lastAdjustmentMode,
+                            target_value: normalizedTargetValue,
+                            actual_state: observedState,
+                            reason: verificationResult.verification?.reason ?? 'direct adjustment did not converge yet'
+                        });
+                        if (verificationResult.withinTolerance) {
+                            const uiFingerprintAfter = await ToolsInteract._captureFingerprint(resolvedPlatform, resolvedDeviceId);
+                            const base = buildActionExecutionResult({
+                                actionType,
+                                sourceModule: 'interact',
+                                device: actionDevice ?? currentDevice,
+                                selector: targetSelector,
+                                resolved: resolvedTarget,
+                                success: true,
+                                uiFingerprintBefore: fingerprintBefore,
+                                uiFingerprintAfter,
+                                details: {
+                                    target_value: normalizedTargetValue,
+                                    tolerance: effectiveTolerance,
+                                    property,
+                                    attempts: attemptCount,
+                                    adjustment_mode: lastAdjustmentMode,
+                                    actual_state: observedState,
+                                    converged: true,
+                                    within_tolerance: true,
+                                    reason: verificationResult.verification?.reason ?? 'control converged to target value'
+                                },
+                                traceSteps
+                            });
+                            return {
+                                ...base,
+                                target_state: {
+                                    property,
+                                    target_value: normalizedTargetValue,
+                                    tolerance: effectiveTolerance
+                                },
+                                actual_state: observedState,
+                                within_tolerance: true,
+                                converged: true,
+                                attempts: attemptCount,
+                                adjustment_mode: lastAdjustmentMode
+                            };
+                        }
+                        cachedResolvedMatch = null;
+                        if (attemptCount < attemptsLimit) {
+                            continue;
+                        }
+                    }
+                }
+            }
+            const directions = ToolsInteract._adjustmentDirections(currentEl);
+            if ((directions.increment || directions.decrement) && attemptCount < attemptsLimit) {
+                const { interact, resolved: actionResolved } = await ToolsInteract.getInteractionService(resolvedPlatform, resolvedDeviceId);
+                const adjustByDirection = typeof interact.adjustAccessibleValue === 'function'
+                    ? interact.adjustAccessibleValue.bind(interact)
+                    : null;
+                while (adjustByDirection && attemptCount < attemptsLimit) {
+                    const direction = normalizedTargetValue > (observedState?.value ?? currentValue) ? 'increment' : 'decrement';
+                    if ((direction === 'increment' && !directions.increment) || (direction === 'decrement' && !directions.decrement))
+                        break;
+                    lastAdjustmentMode = 'semantic';
+                    recordTraceStep('execute', 'retry', {
+                        attempt: attemptCount + 1,
+                        mode: 'semantic',
+                        strategy: 'accessibility_increment_decrement',
+                        direction
+                    });
+                    const actionResult = await adjustByDirection({
+                        deviceId: actionResolved.id,
+                        target: resolvedTarget,
+                        property,
+                        direction
+                    });
+                    attemptCount++;
+                    actionDevice = actionResult?.device ?? actionDevice;
+                    if (actionResult?.success === false)
+                        break;
+                    verificationResult = await runVerification();
+                    observedState = verificationResult.observedState;
+                    lastObservedState = observedState;
+                    recordTraceStep('verify', verificationResult.withinTolerance ? 'success' : 'retry', {
+                        attempt: attemptCount,
+                        property,
+                        target_value: normalizedTargetValue,
+                        actual_state: observedState,
+                        reason: verificationResult.verification?.reason ?? 'incremental adjustment did not converge yet'
+                    });
+                    if (verificationResult.withinTolerance) {
+                        const uiFingerprintAfter = await ToolsInteract._captureFingerprint(resolvedPlatform, resolvedDeviceId);
+                        const base = buildActionExecutionResult({
+                            actionType,
+                            sourceModule: 'interact',
+                            device: actionDevice ?? currentDevice,
+                            selector: targetSelector,
+                            resolved: resolvedTarget,
+                            success: true,
+                            uiFingerprintBefore: fingerprintBefore,
+                            uiFingerprintAfter,
+                            details: {
+                                target_value: normalizedTargetValue,
+                                tolerance: effectiveTolerance,
+                                property,
+                                attempts: attemptCount,
+                                adjustment_mode: lastAdjustmentMode,
+                                actual_state: observedState,
+                                converged: true,
+                                within_tolerance: true,
+                                reason: verificationResult.verification?.reason ?? 'control converged to target value'
+                            },
+                            traceSteps
+                        });
+                        return {
+                            ...base,
+                            target_state: {
+                                property,
+                                target_value: normalizedTargetValue,
+                                tolerance: effectiveTolerance
+                            },
                             actual_state: observedState,
-                            converged: true,
                             within_tolerance: true,
-                            reason: verificationResult.verification?.reason ?? 'control converged to target value'
-                        },
-                        traceSteps
+                            converged: true,
+                            attempts: attemptCount,
+                            adjustment_mode: lastAdjustmentMode
+                        };
+                    }
+                    cachedResolvedMatch = null;
+                    if (attemptCount < attemptsLimit) {
+                        continue adjustmentAttempts;
+                    }
+                }
+            }
+            if (!bounds) {
+                return buildFailure('ELEMENT_NOT_INTERACTABLE', 'adjustable control has no bounds', resolvedTarget, currentDevice, actualState, attemptCount, lastAdjustmentMode, false);
+            }
+            if (!valueRange) {
+                return buildFailure('UNKNOWN', 'value_range unavailable', resolvedTarget, currentDevice, actualState, attemptCount, lastAdjustmentMode, false);
+            }
+            const min = valueRange.min;
+            const max = valueRange.max;
+            const axis = ToolsInteract._controlAxis(currentEl, bounds);
+            const targetPoint = ToolsInteract._buildConservativeControlPoint(bounds, normalizedTargetValue, currentValue, min, max, axis);
+            const currentPoint = ToolsInteract._buildControlPoint(bounds, (currentValue - min) / (max - min), axis);
+            if (!coordinateTapsAwaitingFreshGesture) {
+                const probePoints = inferredSliderState
+                    ? [targetPoint]
+                    : ToolsInteract._buildAdjustmentProbePoints(bounds, normalizedTargetValue, currentValue, min, max, axis);
+                for (let i = 0; i < probePoints.length && attemptCount < attemptsLimit; i++) {
+                    const probePoint = probePoints[i];
+                    lastAdjustmentMode = 'coordinate';
+                    recordTraceStep('execute', 'retry', {
+                        attempt: attemptCount + 1,
+                        mode: 'coordinate',
+                        point: probePoint
                     });
-                    return {
-                        ...base,
-                        target_state: {
-                            property,
-                            target_value: targetValue,
-                            tolerance: normalizedTolerance
-                        },
+                    const actionResult = await ToolsInteract.tapHandler({
+                        platform: resolvedPlatform,
+                        x: probePoint.x,
+                        y: probePoint.y,
+                        deviceId: resolvedDeviceId
+                    });
+                    attemptCount++;
+                    actionDevice = actionResult.device ?? actionDevice;
+                    if (!actionResult.success) {
+                        recordTraceStep('execute', 'retry', {
+                            attempt: attemptCount,
+                            mode: 'coordinate',
+                            point: probePoint,
+                            success: false
+                        });
+                        continue;
+                    }
+                    verificationResult = await runVerification();
+                    observedState = verificationResult.observedState;
+                    lastObservedState = observedState;
+                    recordTraceStep('verify', verificationResult.withinTolerance ? 'success' : 'retry', {
+                        attempt: attemptCount,
+                        property,
+                        target_value: normalizedTargetValue,
                         actual_state: observedState,
-                        within_tolerance: true,
-                        converged: true,
-                        attempts: attemptCount,
-                        adjustment_mode: lastAdjustmentMode
-                    };
+                        reason: verificationResult.verification?.reason ?? 'control did not converge yet'
+                    });
+                    if (verificationResult.withinTolerance) {
+                        const uiFingerprintAfter = await ToolsInteract._captureFingerprint(resolvedPlatform, resolvedDeviceId);
+                        const base = buildActionExecutionResult({
+                            actionType,
+                            sourceModule: 'interact',
+                            device: actionDevice ?? currentDevice,
+                            selector: targetSelector,
+                            resolved: resolvedTarget,
+                            success: true,
+                            uiFingerprintBefore: fingerprintBefore,
+                            uiFingerprintAfter,
+                            details: {
+                                target_value: normalizedTargetValue,
+                                tolerance: effectiveTolerance,
+                                property,
+                                attempts: attemptCount,
+                                adjustment_mode: lastAdjustmentMode,
+                                actual_state: observedState,
+                                converged: true,
+                                within_tolerance: true,
+                                reason: verificationResult.verification?.reason ?? 'control converged to target value'
+                            },
+                            traceSteps
+                        });
+                        return {
+                            ...base,
+                            target_state: {
+                                property,
+                                target_value: normalizedTargetValue,
+                                tolerance: effectiveTolerance
+                            },
+                            actual_state: observedState,
+                            within_tolerance: true,
+                            converged: true,
+                            attempts: attemptCount,
+                            adjustment_mode: lastAdjustmentMode
+                        };
+                    }
+                    coordinateTapsAwaitingFreshGesture = true;
+                    cachedResolvedMatch = null;
+                    if (attemptCount < attemptsLimit) {
+                        continue adjustmentAttempts;
+                    }
                 }
             }
-            if (currentValue !== null) {
+            if (attemptCount < attemptsLimit) {
+                coordinateTapsAwaitingFreshGesture = false;
                 lastAdjustmentMode = 'gesture';
                 recordTraceStep('execute', 'retry', {
                     attempt: attemptCount + 1,
@@ -958,7 +1626,7 @@ export class ToolsInteract {
                     y1: currentPoint.y,
                     x2: targetPoint.x,
                     y2: targetPoint.y,
-                    duration: 220,
+                    duration: inferredSliderState ? 520 : 220,
                     deviceId: resolvedDeviceId
                 });
                 attemptCount++;
@@ -979,7 +1647,7 @@ export class ToolsInteract {
                 recordTraceStep('verify', verificationResult.withinTolerance ? 'success' : 'retry', {
                     attempt: attemptCount,
                     property,
-                    target_value: targetValue,
+                    target_value: normalizedTargetValue,
                     actual_state: observedState,
                     reason: verificationResult.verification?.reason ?? 'gesture adjustment did not converge yet'
                 });
@@ -995,8 +1663,8 @@ export class ToolsInteract {
                         uiFingerprintBefore: fingerprintBefore,
                         uiFingerprintAfter,
                         details: {
-                            target_value: targetValue,
-                            tolerance: normalizedTolerance,
+                            target_value: normalizedTargetValue,
+                            tolerance: effectiveTolerance,
                             property,
                             attempts: attemptCount,
                             adjustment_mode: lastAdjustmentMode,
@@ -1011,8 +1679,8 @@ export class ToolsInteract {
                         ...base,
                         target_state: {
                             property,
-                            target_value: targetValue,
-                            tolerance: normalizedTolerance
+                            target_value: normalizedTargetValue,
+                            tolerance: effectiveTolerance
                         },
                         actual_state: observedState,
                         within_tolerance: true,
@@ -1028,7 +1696,7 @@ export class ToolsInteract {
                 recordTraceStep('verify', 'success', {
                     attempt: attemptCount,
                     property,
-                    target_value: targetValue,
+                    target_value: normalizedTargetValue,
                     actual_state: observedState,
                     reason: verification?.reason ?? 'control converged to target value'
                 });
@@ -1043,8 +1711,8 @@ export class ToolsInteract {
                     uiFingerprintBefore: fingerprintBefore,
                     uiFingerprintAfter,
                     details: {
-                        target_value: targetValue,
-                        tolerance: normalizedTolerance,
+                        target_value: normalizedTargetValue,
+                        tolerance: effectiveTolerance,
                         property,
                         attempts: attemptCount,
                         adjustment_mode: lastAdjustmentMode,
@@ -1059,8 +1727,8 @@ export class ToolsInteract {
                     ...base,
                     target_state: {
                         property,
-                        target_value: targetValue,
-                        tolerance: normalizedTolerance
+                        target_value: normalizedTargetValue,
+                        tolerance: effectiveTolerance
                     },
                     actual_state: observedState,
                     within_tolerance: true,
@@ -1069,22 +1737,24 @@ export class ToolsInteract {
                     adjustment_mode: lastAdjustmentMode
                 };
             }
-            cachedResolvedMatch = {
-                el: {
-                    ...currentEl,
-                    state: {
-                        ...(currentEl.state ?? null),
-                        ...(observedState ? {
-                            [observedState.property]: observedState.value,
-                            raw_value: observedState.raw_value ?? observedState.value
-                        } : {})
-                    }
-                },
-                idx: resolved.match.idx
-            };
+            cachedResolvedMatch = inferredSliderState
+                ? null
+                : {
+                    el: {
+                        ...currentEl,
+                        state: {
+                            ...(currentEl.state ?? null),
+                            ...(observedState ? {
+                                [observedState.property]: observedState.value,
+                                raw_value: observedState.raw_value ?? observedState.value
+                            } : {})
+                        }
+                    },
+                    idx: resolved.match.idx
+                };
         }
         const uiFingerprintAfter = await ToolsInteract._captureFingerprint(resolvedPlatform, resolvedDeviceId);
-        return buildFailure('TIMEOUT', 'control did not converge within the allotted attempts', resolvedTarget, currentDevice, lastObservedState, attemptCount, lastAdjustmentMode, true, uiFingerprintAfter);
+        return buildFailure('CONTROL_CONVERGENCE_FAILED', 'control did not converge within the allotted attempts', resolvedTarget, currentDevice, lastObservedState, attemptCount, lastAdjustmentMode, true, uiFingerprintAfter);
     }
     static async swipeHandler({ platform = 'android', x1, y1, x2, y2, duration, deviceId }) {
         const { interact, resolved } = await ToolsInteract.getInteractionService(platform, deviceId);
@@ -1711,24 +2381,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 +2455,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 +2484,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'
         };
     }