mobile-debug-mcp 0.34.0 → 0.35.0

package/dist/interact/index.js

@@ -1,180 +1,29 @@
-import { checkDebuggerGuard } from '../debugger/guard.js';
-import { currentReadinessWait, observeReadinessWait, isDeviceUnavailable } from '../observe/readiness.js';
-import { readinessDelay } from '../observe/readiness-service.js';
+import { resolveTap } from './targeting/tap-target.js';
+import { waitForUICore } from './waits/legacy-wait.js';
+import { expectState } from './assertions/state-assertion.js';
+import { waitForUIChange } from './waits/ui-change-wait.js';
+import { waitForScreenChange } from './waits/screen-wait.js';
+import { expectScreen } from './assertions/screen-assertion.js';
+import { expectVisible } from './assertions/visibility-assertion.js';
+import { findElement } from './targeting/find-element.js';
+import { waitForUI } from './waits/ui-wait.js';
+import { adjustControl } from './adjustment/adjustment.js';
+import { ResolvedElements } from './targeting/resolved-elements.js';
+import { findScopedElement, resolveUiChangeScope } from './targeting/target-scope.js';
+import { _normalizeBounds, _computeElementId, _resolvedTargetFromElement } from './targeting/element-helpers.js';
+import { _collectSubtreeIndices } from './waits/ui-change-helpers.js';
 import { isConditionBlocked } from './conditional-action.js';
-import { remainingBudget } from '../utils/operation-budget.js';
-import { createHash } from 'crypto';
 import { AndroidInteract } from './android.js';
 import { iOSInteract } from './ios.js';
 export { AndroidInteract, iOSInteract };
 import { resolveTargetDevice } from '../utils/resolve-device.js';
 import { ToolsObserve } from '../observe/index.js';
-import { computeSnapshotSignature } from '../observe/snapshot-metadata.js';
-import { buildActionExecutionResult, createTraceStep, nextActionId } from '../server/common.js';
-function buildObservationTrace({ actionType, stage, success, attempts, metadata }) {
-    const now = Date.now();
-    const actionId = nextActionId(actionType, now);
-    const steps = [
-        createTraceStep({
-            stage,
-            timestamp: now,
-            result: success ? 'success' : 'failure',
-            attemptIndex: 0,
-            metadata
-        })
-    ];
-    return {
-        action_id: actionId,
-        steps,
-        final_outcome: success ? 'success' : 'failure',
-        attempts: Math.max(1, Math.floor(attempts || 1))
-    };
-}
+import { buildActionExecutionResult } from '../runtime/action-results.js';
 export class ToolsInteract {
     static _maxResolvedUiElements = 256;
-    static _uiChangeKinds = ['hierarchy_diff', 'text_change', 'state_change'];
-    static _sliderSearchLookahead = 8;
-    static _sliderNegativeGapTolerancePx = 32;
-    static _sliderPositiveGapLimitPx = 640;
-    static _sliderTrackMinLengthPx = 220;
-    static _sliderTrackMaxThicknessPx = 180;
-    static _sliderTrackLengthRatio = 0.18;
-    static _sliderTrackThicknessRatio = 0.08;
-    static _sliderLabelWidthRatio = 1.5;
-    static _resolvedUiElements = new Map();
-    static _normalize(s) {
-        if (s === null || s === undefined)
-            return '';
-        try {
-            return String(s).toLowerCase().trim();
-        }
-        catch {
-            return '';
-        }
-    }
-    static _normalizeBounds(bounds) {
-        if (!Array.isArray(bounds) || bounds.length < 4)
-            return null;
-        const normalized = bounds.slice(0, 4).map((value) => Number(value));
-        if (normalized.some((value) => Number.isNaN(value)))
-            return null;
-        return normalized;
-    }
-    static _hash(value) {
-        return createHash('sha256').update(JSON.stringify(value)).digest('hex');
-    }
-    static _matchesSelector(el, selector) {
-        if (!selector)
-            return false;
-        const normalize = ToolsInteract._normalize;
-        const containsFlag = !!selector.contains;
-        const text = normalize(el.text ?? el.label ?? el.value ?? '');
-        const resourceId = normalize(el.resourceId ?? el.resourceID ?? el.id ?? '');
-        const accessibilityId = normalize(el.contentDescription ?? el.contentDesc ?? el.accessibilityLabel ?? el.label ?? '');
-        if (selector.text !== undefined && selector.text !== null) {
-            const q = normalize(selector.text);
-            if (containsFlag ? !text.includes(q) : text !== q)
-                return false;
-        }
-        if (selector.resource_id !== undefined && selector.resource_id !== null) {
-            const q = normalize(selector.resource_id);
-            if (containsFlag ? !resourceId.includes(q) : resourceId !== q)
-                return false;
-        }
-        if (selector.accessibility_id !== undefined && selector.accessibility_id !== null) {
-            const q = normalize(selector.accessibility_id);
-            if (containsFlag ? !accessibilityId.includes(q) : accessibilityId !== q)
-                return false;
-        }
-        return true;
-    }
-    static _findFirstMatchingElement(elements, selector) {
-        if (!selector)
-            return null;
-        for (let i = 0; i < elements.length; i++) {
-            const el = elements[i];
-            if (!el)
-                continue;
-            if (ToolsInteract._matchesSelector(el, selector))
-                return { el, idx: i };
-        }
-        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,
-            deviceId: deviceId || '',
-            text: ToolsInteract._normalize(el.text ?? el.label ?? el.value ?? ''),
-            resourceId: ToolsInteract._normalize(el.resourceId ?? el.resourceID ?? el.id ?? ''),
-            accessibilityId: ToolsInteract._normalize(el.contentDescription ?? el.contentDesc ?? el.accessibilityLabel ?? el.label ?? ''),
-            class: ToolsInteract._normalize(el.type ?? el.class ?? ''),
-            bounds: ToolsInteract._normalizeBounds(el.bounds) ?? [0, 0, 0, 0],
-            index
-        };
-        return `el_${createHash('sha1').update(JSON.stringify(identity)).digest('hex').slice(0, 24)}`;
-    }
+    static _resolvedUiElements = new ResolvedElements(ToolsInteract._maxResolvedUiElements);
+    static _normalizeBounds = _normalizeBounds;
+    static _computeElementId = _computeElementId;
     static _buildResolvedElement(platform, deviceId, el, index) {
         const bounds = ToolsInteract._normalizeBounds(el.bounds);
         const elementId = ToolsInteract._computeElementId(platform, deviceId, el, index);
@@ -203,224 +52,14 @@ export class ToolsInteract {
         };
     }
     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);
+        return resolveUiChangeScope(tree, scope, target, (snapshot, id) => ToolsInteract._findScopedElement(snapshot, id));
     }
-    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 _findScopedElement(tree, id) {
+        return findScopedElement(tree, id, ToolsInteract._resolvedUiElements);
     }
+    static _collectSubtreeIndices = _collectSubtreeIndices;
     static _rememberResolvedElement(elementId, context) {
-        if (ToolsInteract._resolvedUiElements.has(elementId)) {
-            ToolsInteract._resolvedUiElements.delete(elementId);
-        }
-        ToolsInteract._resolvedUiElements.set(elementId, context);
-        while (ToolsInteract._resolvedUiElements.size > ToolsInteract._maxResolvedUiElements) {
-            const oldestElementId = ToolsInteract._resolvedUiElements.keys().next().value;
-            if (!oldestElementId)
-                break;
-            ToolsInteract._resolvedUiElements.delete(oldestElementId);
-        }
+        ToolsInteract._resolvedUiElements.remember(elementId, context);
     }
     static async _captureFingerprint(platform, deviceId) {
         if (isConditionBlocked())
@@ -433,402 +72,7 @@ export class ToolsInteract {
             return null;
         }
     }
-    static _buildUiChangeSignatures(tree) {
-        const elements = Array.isArray(tree?.elements) ? tree.elements : [];
-        const textPayload = [];
-        const statePayload = [];
-        for (const el of elements) {
-            textPayload.push({
-                text: ToolsInteract._normalize(el?.text ?? el?.label ?? el?.value ?? ''),
-                contentDescription: ToolsInteract._normalize(el?.contentDescription ?? el?.contentDesc ?? el?.accessibilityLabel ?? ''),
-                resourceId: ToolsInteract._normalize(el?.resourceId ?? el?.resourceID ?? el?.id ?? '')
-            });
-            statePayload.push({
-                checked: el?.state?.checked ?? null,
-                selected: el?.state?.selected ?? null,
-                focused: el?.state?.focused ?? null,
-                expanded: el?.state?.expanded ?? null,
-                enabled: el?.state?.enabled ?? null,
-                text_value: el?.state?.text_value ?? null,
-                value: el?.state?.value ?? null,
-                raw_value: el?.state?.raw_value ?? null,
-                value_range: el?.state?.value_range ?? null
-            });
-        }
-        return {
-            hierarchy: computeSnapshotSignature(tree),
-            text: ToolsInteract._hash({
-                screen: ToolsInteract._normalize(tree?.screen),
-                elements: textPayload
-            }),
-            state: ToolsInteract._hash({
-                screen: ToolsInteract._normalize(tree?.screen),
-                elements: statePayload
-            })
-        };
-    }
-    static _matchesUiChange(expected, initial, current) {
-        const candidates = expected ? [expected] : ToolsInteract._uiChangeKinds;
-        for (const changeKind of candidates) {
-            if (changeKind === 'hierarchy_diff' && initial.hierarchy !== current.hierarchy)
-                return changeKind;
-            if (changeKind === 'text_change' && initial.text !== current.text)
-                return changeKind;
-            if (changeKind === 'state_change' && initial.state !== current.state)
-                return changeKind;
-        }
-        return null;
-    }
-    static _uiChangeSignaturesEqual(left, right) {
-        return left.hierarchy === right.hierarchy && left.text === right.text && left.state === right.state;
-    }
-    static _resolvedTargetFromElement(elementId, element, index) {
-        return {
-            elementId,
-            text: element.text ?? null,
-            resource_id: element.resourceId ?? element.resourceID ?? element.id ?? null,
-            accessibility_id: element.contentDescription ?? element.contentDesc ?? element.accessibilityLabel ?? element.label ?? null,
-            class: element.type ?? element.class ?? null,
-            bounds: ToolsInteract._normalizeBounds(element.bounds),
-            index,
-            state: element.state ?? null,
-            stable_id: element.stable_id ?? null,
-            role: element.role ?? null,
-            test_tag: element.test_tag ?? null,
-            selector: element.selector ?? null,
-            semantic: element.semantic ?? null
-        };
-    }
-    static _summarizeResolutionCandidate(candidate) {
-        const bounds = ToolsInteract._normalizeBounds(candidate.el.bounds);
-        return {
-            text: candidate.el.text ?? null,
-            resource_id: candidate.el.resourceId ?? candidate.el.resourceID ?? candidate.el.id ?? null,
-            accessibility_id: candidate.el.contentDescription ?? candidate.el.contentDesc ?? candidate.el.accessibilityLabel ?? candidate.el.label ?? null,
-            class: candidate.el.type ?? candidate.el.class ?? null,
-            bounds: bounds
-                ? { left: bounds[0], top: bounds[1], right: bounds[2], bottom: bounds[3] }
-                : null,
-            clickable: !!candidate.el.clickable,
-            enabled: !!candidate.el.enabled,
-            score: candidate.score,
-            reason: candidate.reason
-        };
-    }
-    static _isAdjustableControl(el) {
-        if (!el)
-            return false;
-        const type = ToolsInteract._normalize(el.type ?? el.class ?? '');
-        const role = ToolsInteract._normalize(el.role ?? '');
-        return !!el.state?.value_range || /slider|seekbar|stepper|adjustable|range/.test(type) || /slider|seekbar|stepper|adjustable|range/.test(role);
-    }
-    static _isSemanticActionable(el) {
-        if (!el?.semantic)
-            return false;
-        if (el.semantic.adjustable)
-            return true;
-        return Array.isArray(el.semantic.supported_actions) && el.semantic.supported_actions.length > 0;
-    }
-    static _readNumericControlValue(el, property) {
-        if (!el?.state)
-            return null;
-        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;
-        const width = Math.max(1, right - left);
-        const height = Math.max(1, bottom - top);
-        const insetX = Math.max(8, Math.floor(width * 0.08));
-        const insetY = Math.max(8, Math.floor(height * 0.08));
-        if (axis === 'vertical') {
-            const usableHeight = Math.max(1, height - (insetY * 2));
-            return {
-                x: Math.floor((left + right) / 2),
-                y: Math.floor(bottom - insetY - (usableHeight * clampedRatio))
-            };
-        }
-        const usableWidth = Math.max(1, width - (insetX * 2));
-        return {
-            x: Math.floor(left + insetX + (usableWidth * clampedRatio)),
-            y: Math.floor((top + bottom) / 2)
-        };
-    }
-    static _buildConservativeControlPoint(bounds, targetValue, currentValue, min, max, axis) {
-        const range = Math.max(1, max - min);
-        const targetRatio = (targetValue - min) / range;
-        const stepRatio = 1 / range;
-        const centerBias = stepRatio / 2;
-        const direction = currentValue === null ? 0 : Math.sign(targetValue - currentValue);
-        const controlLengthPx = axis === 'vertical' ? Math.max(1, bounds[3] - bounds[1]) : Math.max(1, bounds[2] - bounds[0]);
-        const edgeWindow = Math.max(3, Math.floor(range * 0.1));
-        const isNearLowEdge = targetValue - min <= edgeWindow;
-        const isNearHighEdge = max - targetValue <= edgeWindow;
-        const directionBias = direction > 0
-            ? -stepRatio * 0.15
-            : direction < 0
-                ? stepRatio * 0.65
-                : 0;
-        const pixelBasedMargin = Math.min(0.03, Math.max(0.005, 2 / controlLengthPx));
-        const endpointMargin = Math.max(stepRatio * 0.5, pixelBasedMargin);
-        const edgeBias = isNearLowEdge
-            ? endpointMargin
-            : isNearHighEdge
-                ? Math.max(stepRatio * 0.4, endpointMargin * 0.75)
-                : 0;
-        const safeRatio = Math.min(1 - (endpointMargin * 0.25), Math.max(endpointMargin, targetRatio + centerBias + directionBias + edgeBias));
-        return ToolsInteract._buildControlPoint(bounds, safeRatio, axis);
-    }
-    static _buildAdjustmentProbePoints(bounds, targetValue, currentValue, min, max, axis) {
-        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 [left, top, right, bottom] = bounds;
-        const width = Math.max(1, right - left);
-        const height = Math.max(1, bottom - top);
-        const crossAxisBumps = axis === 'horizontal'
-            ? [Math.max(24, Math.floor(height * 0.75)), Math.max(40, Math.floor(height * 1.5))]
-            : [Math.max(24, Math.floor(width * 0.75)), Math.max(40, Math.floor(width * 1.5))];
-        const clampPoint = (point) => ({
-            x: axis === 'horizontal'
-                ? Math.max(left, Math.min(right, point.x))
-                : Math.max(left, Math.min(right + Math.max(width, height), point.x)),
-            y: axis === 'vertical'
-                ? Math.max(top, Math.min(bottom, point.y))
-                : Math.max(top, Math.min(bottom + Math.max(height, width), point.y))
-        });
-        const probes = [targetPoint, currentPoint];
-        for (const bump of crossAxisBumps) {
-            if (axis === 'horizontal') {
-                probes.push({ x: targetPoint.x, y: bottom + bump }, { x: currentPoint.x, y: bottom + bump });
-            }
-            else {
-                probes.push({ x: right + bump, y: targetPoint.y }, { x: right + bump, y: currentPoint.y });
-            }
-        }
-        return Array.from(new Map(probes
-            .map(clampPoint)
-            .map((point) => [`${point.x}:${point.y}`, point])).values());
-    }
-    static _controlAxis(el, bounds) {
-        const type = ToolsInteract._normalize(el.type ?? el.class ?? '');
-        const role = ToolsInteract._normalize(el.role ?? '');
-        if (/vertical/.test(type) || /vertical/.test(role))
-            return 'vertical';
-        if (/horizontal/.test(type) || /horizontal/.test(role))
-            return 'horizontal';
-        return (bounds[3] - bounds[1]) > (bounds[2] - bounds[0]) ? 'vertical' : 'horizontal';
-    }
+    static _resolvedTargetFromElement = _resolvedTargetFromElement;
     static _actionFailure(actionType, selector, resolved, failureCode, retryable, uiFingerprintBefore, uiFingerprintAfter, sourceModule = 'interact') {
         return buildActionExecutionResult({
             actionType,
@@ -851,111 +95,11 @@ export class ToolsInteract {
         }
         return null;
     }
-    static _resolveActionableAncestor(elements, chosen) {
-        if (!chosen)
-            return null;
-        if (chosen.el.clickable || chosen.el.focusable || ToolsInteract._isSemanticActionable(chosen.el))
-            return chosen;
-        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 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 {
-                break;
-            }
-            safety++;
-        }
-        const childBounds = ToolsInteract._normalizeBounds(chosen.el.bounds);
-        if (!childBounds)
-            return null;
-        const [cl, ct, cr, cb] = childBounds;
-        let best = null;
-        let bestArea = Infinity;
-        for (let i = 0; i < elements.length; i++) {
-            const el = elements[i];
-            if (!el || !(el.clickable || el.focusable || ToolsInteract._isSemanticActionable(el)))
-                continue;
-            const bounds = ToolsInteract._normalizeBounds(el.bounds);
-            if (!bounds)
-                continue;
-            const [pl, pt, pr, pb] = bounds;
-            if (pl <= cl && pt <= ct && pr >= cr && pb >= cb) {
-                const area = (pr - pl) * (pb - pt);
-                if (area < bestArea) {
-                    bestArea = area;
-                    best = { el, idx: i };
-                }
-            }
-        }
-        return best;
-    }
-    static _resolveNearbyActionableControl(elements, chosen, screen) {
-        if (!chosen)
-            return null;
-        const labelBounds = ToolsInteract._normalizeBounds(chosen.el.bounds);
-        if (!labelBounds)
-            return null;
-        const [labelLeft, labelTop, labelRight, labelBottom] = labelBounds;
-        const labelWidth = labelRight - labelLeft;
-        const labelHeight = labelBottom - labelTop;
-        const screenWidth = Number(screen?.width) > 0 ? Number(screen?.width) : 0;
-        const screenHeight = Number(screen?.height) > 0 ? Number(screen?.height) : 0;
-        const minTrackLengthPx = Math.max(ToolsInteract._sliderTrackMinLengthPx, screenWidth > 0 ? Math.floor(screenWidth * ToolsInteract._sliderTrackLengthRatio) : 0, screenHeight > 0 ? Math.floor(screenHeight * ToolsInteract._sliderTrackLengthRatio) : 0);
-        const maxTrackThicknessPx = Math.max(ToolsInteract._sliderTrackMaxThicknessPx, screenWidth > 0 ? Math.floor(screenWidth * ToolsInteract._sliderTrackThicknessRatio) : 0, screenHeight > 0 ? Math.floor(screenHeight * ToolsInteract._sliderTrackThicknessRatio) : 0);
-        let best = null;
-        let bestScore = Infinity;
-        for (let i = chosen.idx + 1; i < Math.min(elements.length, chosen.idx + ToolsInteract._sliderSearchLookahead); i++) {
-            const candidate = elements[i];
-            if (!candidate || !(candidate.clickable || candidate.focusable) || candidate.visible === false)
-                continue;
-            const candidateBounds = ToolsInteract._normalizeBounds(candidate.bounds);
-            if (!candidateBounds)
-                continue;
-            const [left, top, right] = candidateBounds;
-            const width = right - left;
-            const height = candidateBounds[3] - top;
-            const verticalGap = top - labelBottom;
-            if (verticalGap < -ToolsInteract._sliderNegativeGapTolerancePx || verticalGap > ToolsInteract._sliderPositiveGapLimitPx)
-                continue;
-            const horizontalOverlap = Math.min(labelRight, right) - Math.max(labelLeft, left);
-            if (horizontalOverlap < -ToolsInteract._sliderNegativeGapTolerancePx)
-                continue;
-            const candidateText = ToolsInteract._normalize(candidate.text ?? candidate.label ?? candidate.value ?? '');
-            const candidateContent = ToolsInteract._normalize(candidate.contentDescription ?? candidate.contentDesc ?? candidate.accessibilityLabel ?? '');
-            const candidateClass = ToolsInteract._normalize(candidate.type ?? candidate.class ?? '');
-            let score = verticalGap;
-            const horizontalTrackLike = width >= Math.max(minTrackLengthPx, Math.floor(labelWidth * ToolsInteract._sliderLabelWidthRatio)) &&
-                height <= maxTrackThicknessPx;
-            const verticalTrackLike = height >= Math.max(minTrackLengthPx, Math.floor(labelHeight * ToolsInteract._sliderLabelWidthRatio)) &&
-                width <= maxTrackThicknessPx;
-            const trackLike = /slider|seek|range/i.test(candidateClass) || horizontalTrackLike || verticalTrackLike;
-            if (!candidateText && !candidateContent)
-                score -= 18;
-            if (trackLike)
-                score -= 30;
-            if (/view|layout|group|frame/i.test(candidateClass))
-                score -= 10;
-            if (width > labelWidth * ToolsInteract._sliderLabelWidthRatio)
-                score -= 8;
-            if (candidateText || candidateContent)
-                score += 20;
-            if (score < bestScore) {
-                bestScore = score;
-                best = { el: candidate, idx: i, sliderLike: trackLike };
-            }
-        }
-        return best;
-    }
     static async getInteractionService(platform, deviceId) {
         const effectivePlatform = platform || 'android';
         const resolved = await resolveTargetDevice({ platform: effectivePlatform, deviceId });
         const interact = effectivePlatform === 'android' ? new AndroidInteract() : new iOSInteract();
-        return { interact: interact, resolved, platform: effectivePlatform };
+        return { interact, resolved, platform: effectivePlatform };
     }
     static async tapHandler({ platform, x, y, deviceId, timeoutMs }) {
         const { interact, resolved } = await ToolsInteract.getInteractionService(platform, deviceId);
@@ -970,24 +114,14 @@ export class ToolsInteract {
         }
         const fingerprintBefore = verificationMode === 'full' ? await ToolsInteract._captureFingerprint(resolved.platform, resolved.deviceId) : null;
         const tree = freshTree ?? await ToolsObserve.getUITreeHandler({ platform: resolved.platform, deviceId: resolved.deviceId });
-        const treePlatform = tree?.device?.platform === 'ios' ? 'ios' : resolved.platform;
-        const treeDeviceId = tree?.device?.id || resolved.deviceId;
-        const elements = Array.isArray(tree?.elements) ? tree.elements : [];
-        const currentMatch = ToolsInteract._findCurrentResolvedElement(elements, treePlatform, treeDeviceId, resolved);
-        if (!currentMatch) {
-            return ToolsInteract._actionFailure(actionType, selector, null, 'STALE_REFERENCE', true, fingerprintBefore);
-        }
-        const resolvedTarget = ToolsInteract._resolvedTargetFromElement(resolved.elementId, currentMatch.el, currentMatch.index);
-        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]) {
-            return ToolsInteract._actionFailure(actionType, selector, resolvedTarget, 'ELEMENT_NOT_INTERACTABLE', true, fingerprintBefore);
-        }
-        const x = Math.floor((bounds[0] + bounds[2]) / 2);
-        const y = Math.floor((bounds[1] + bounds[3]) / 2);
+        const tap = resolveTap(tree, resolved, {
+            current: (elements, platform, deviceId, handle) => ToolsInteract._findCurrentResolvedElement(elements, platform, deviceId, handle),
+            target: (element, index) => ToolsInteract._resolvedTargetFromElement(resolved.elementId, element, index)
+        });
+        if ('failure' in tap)
+            return ToolsInteract._actionFailure(actionType, selector, tap.target, tap.failure, true, fingerprintBefore);
+        const resolvedTarget = tap.target;
+        const { x, y } = tap.point;
         const tapResult = await ToolsInteract.tapHandler({ platform: resolved.platform, x, y, deviceId: resolved.deviceId, timeoutMs });
         if (!tapResult.success) {
             const fingerprintAfterFailure = verificationMode === 'full' ? await ToolsInteract._captureFingerprint(resolved.platform, resolved.deviceId) : null;
@@ -1005,763 +139,17 @@ export class ToolsInteract {
             sourceModule: 'interact'
         });
     }
-    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 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 = [];
-        let traceAttemptIndex = 0;
-        const recordTraceStep = (stage, result, metadata) => {
-            traceSteps.push(createTraceStep({
-                stage,
-                timestamp: Date.now(),
-                result,
-                attemptIndex: traceAttemptIndex++,
-                metadata
-            }));
-        };
-        const buildFailure = (failureCode, reason, resolved, device, actualState, attempts, adjustmentMode = 'gesture', retryable = false, uiFingerprintAfter = null) => {
-            if (!traceSteps.some((step) => step.stage === 'resolve')) {
-                recordTraceStep('resolve', 'failure', {
-                    reason,
-                    failure_code: failureCode
-                });
-            }
-            if (!traceSteps.some((step) => step.stage === 'recover')) {
-                recordTraceStep('recover', retryable ? 'retry' : 'failure', {
-                    reason,
-                    failure_code: failureCode,
-                    retry_allowed: retryable,
-                    recovery_attempts: attempts,
-                    retry_depth: attempts
-                });
-            }
-            const responseTolerance = requestedTolerance ?? 0;
-            const base = buildActionExecutionResult({
-                actionType,
-                sourceModule: 'interact',
-                device,
-                selector: targetSelector,
-                resolved,
-                success: false,
-                uiFingerprintBefore: fingerprintBefore,
-                uiFingerprintAfter,
-                failure: { failureCode, retryable },
-                details: {
-                    target_value: targetValue,
-                    tolerance: responseTolerance,
-                    property,
-                    attempts,
-                    adjustment_mode: adjustmentMode,
-                    actual_state: actualState,
-                    converged: false,
-                    within_tolerance: false,
-                    reason
-                },
-                traceSteps
-            });
-            return {
-                ...base,
-                target_state: {
-                    property,
-                    target_value: targetValue,
-                    tolerance: responseTolerance
-                },
-                actual_state: actualState,
-                within_tolerance: false,
-                converged: false,
-                attempts,
-                adjustment_mode: adjustmentMode
-            };
-        };
-        const resolveCurrentMatch = async () => {
-            const tree = await ToolsObserve.getUITreeHandler({ platform: resolvedPlatform, deviceId: resolvedDeviceId });
-            resolvedPlatform = tree?.device?.platform === 'ios' ? 'ios' : resolvedPlatform;
-            resolvedDeviceId = tree?.device?.id || resolvedDeviceId;
-            const elements = Array.isArray(tree?.elements) ? tree.elements : [];
-            if (element_id) {
-                const stored = ToolsInteract._resolvedUiElements.get(element_id);
-                if (!stored) {
-                    return null;
-                }
-                const current = ToolsInteract._findCurrentResolvedElement(elements, resolvedPlatform, resolvedDeviceId, stored);
-                if (!current) {
-                    return null;
-                }
-                return {
-                    tree,
-                    device: tree?.device,
-                    match: { el: current.el, idx: current.index },
-                    resolvedTarget: ToolsInteract._resolvedTargetFromElement(ToolsInteract._computeElementId(resolvedPlatform, resolvedDeviceId, current.el, current.index), current.el, current.index)
-                };
-            }
-            if (semanticFallbackElement) {
-                const fallbackBounds = ToolsInteract._normalizeBounds(Array.isArray(semanticFallbackElement.bounds)
-                    ? semanticFallbackElement.bounds
-                    : semanticFallbackElement.bounds && typeof semanticFallbackElement.bounds === 'object'
-                        ? [
-                            Number(semanticFallbackElement.bounds.left),
-                            Number(semanticFallbackElement.bounds.top),
-                            Number(semanticFallbackElement.bounds.right),
-                            Number(semanticFallbackElement.bounds.bottom)
-                        ]
-                        : null);
-                let matchedIndex = -1;
-                if (fallbackBounds) {
-                    matchedIndex = elements.findIndex((el) => {
-                        const bounds = ToolsInteract._normalizeBounds(el.bounds);
-                        return !!bounds && bounds[0] === fallbackBounds[0] && bounds[1] === fallbackBounds[1] && bounds[2] === fallbackBounds[2] && bounds[3] === fallbackBounds[3];
-                    });
-                }
-                if (matchedIndex === -1 && fallbackBounds) {
-                    const fallbackCenterX = Math.floor((fallbackBounds[0] + fallbackBounds[2]) / 2);
-                    const fallbackCenterY = Math.floor((fallbackBounds[1] + fallbackBounds[3]) / 2);
-                    let bestDistance = Infinity;
-                    for (let i = 0; i < elements.length; i++) {
-                        const el = elements[i];
-                        if (!ToolsInteract._isAdjustableControl(el))
-                            continue;
-                        const bounds = ToolsInteract._normalizeBounds(el.bounds);
-                        if (!bounds)
-                            continue;
-                        const centerX = Math.floor((bounds[0] + bounds[2]) / 2);
-                        const centerY = Math.floor((bounds[1] + bounds[3]) / 2);
-                        const distance = Math.abs(centerX - fallbackCenterX) + Math.abs(centerY - fallbackCenterY);
-                        if (distance < bestDistance) {
-                            bestDistance = distance;
-                            matchedIndex = i;
-                        }
-                    }
-                }
-                if (matchedIndex >= 0 && elements[matchedIndex]) {
-                    const matched = { el: elements[matchedIndex], idx: matchedIndex };
-                    return {
-                        tree,
-                        device: tree?.device,
-                        match: matched,
-                        resolvedTarget: ToolsInteract._resolvedTargetFromElement(ToolsInteract._computeElementId(resolvedPlatform, resolvedDeviceId, matched.el, matched.idx), matched.el, matched.idx)
-                    };
-                }
-            }
-            if (selector) {
-                const matched = ToolsInteract._findFirstMatchingElement(elements, selector);
-                if (!matched) {
-                    return null;
-                }
-                return {
-                    tree,
-                    device: tree?.device,
-                    match: matched,
-                    resolvedTarget: ToolsInteract._resolvedTargetFromElement(ToolsInteract._computeElementId(resolvedPlatform, resolvedDeviceId, matched.el, matched.idx), matched.el, matched.idx)
-                };
-            }
-            return null;
-        };
-        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({
-                selector,
-                condition: 'clickable',
-                timeout_ms: 5000,
-                poll_interval_ms: 300,
-                platform: resolvedPlatform,
-                deviceId: resolvedDeviceId
-            });
-            if (waitResult?.status !== 'success' || !waitResult?.element?.elementId) {
-                const semanticQuery = selector.text ?? selector.resource_id ?? selector.accessibility_id ?? '';
-                if (!semanticQuery) {
-                    return buildFailure(waitResult?.error?.code === 'ELEMENT_NOT_FOUND' ? 'ELEMENT_NOT_FOUND' : 'TIMEOUT', waitResult?.error?.message ?? 'adjustable control not found', null, waitResult?.device, null, 0, 'gesture', waitResult?.error?.code === 'ELEMENT_NOT_FOUND');
-                }
-                const fallback = await ToolsInteract.findElementHandler({
-                    query: semanticQuery,
-                    exact: false,
-                    timeoutMs: 3000,
-                    platform: resolvedPlatform,
-                    deviceId: resolvedDeviceId
-                });
-                if (!fallback.found || !fallback.element) {
-                    return buildFailure('ELEMENT_NOT_FOUND', waitResult?.error?.message ?? 'adjustable control not found', null, waitResult?.device, null, 0, 'gesture', true);
-                }
-                semanticFallbackElement = fallback.element;
-            }
-            else {
-                element_id = waitResult.element.elementId;
-                semanticFallbackElement = null;
-            }
-        }
-        let lastObservedState = null;
-        let lastAdjustmentMode = 'gesture';
-        let resolvedTarget = null;
-        let currentDevice = undefined;
-        let attemptCount = 0;
-        let cachedResolvedMatch = null;
-        let coordinateTapsAwaitingFreshGesture = false;
-        adjustmentAttempts: for (let attempt = 0; attempt < attemptsLimit && attemptCount < attemptsLimit; attempt++) {
-            const resolved = cachedResolvedMatch
-                ? {
-                    tree: null,
-                    device: currentDevice,
-                    match: cachedResolvedMatch,
-                    resolvedTarget: ToolsInteract._resolvedTargetFromElement(ToolsInteract._computeElementId(resolvedPlatform, resolvedDeviceId, cachedResolvedMatch.el, cachedResolvedMatch.idx), cachedResolvedMatch.el, cachedResolvedMatch.idx)
-                }
-                : await resolveCurrentMatch();
-            if (!resolved || !resolved.match || !resolved.resolvedTarget) {
-                return buildFailure('STALE_REFERENCE', 'adjustable control could not be resolved', resolvedTarget, currentDevice, lastObservedState, attemptCount, lastAdjustmentMode, true);
-            }
-            currentDevice = resolved.device;
-            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 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
-                        : inferredSliderState?.current
-                }
-                : null;
-            lastObservedState = actualState;
-            if (!traceSteps.some((step) => step.stage === 'resolve')) {
-                recordTraceStep('resolve', 'success', {
-                    resolved_target: resolvedTarget,
-                    current_value: currentValue,
-                    adjustment_mode: lastAdjustmentMode
-                });
-            }
-            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);
-            }
-            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: normalizedTargetValue,
-                    actual_state: actualState,
-                    reason: 'control already within tolerance'
-                });
-                const uiFingerprintAfter = await ToolsInteract._captureFingerprint(resolvedPlatform, resolvedDeviceId);
-                const base = buildActionExecutionResult({
-                    actionType,
-                    sourceModule: 'interact',
-                    device: currentDevice,
-                    selector: targetSelector,
-                    resolved: resolvedTarget,
-                    success: true,
-                    uiFingerprintBefore: fingerprintBefore,
-                    uiFingerprintAfter,
-                    details: {
-                        target_value: normalizedTargetValue,
-                        tolerance: effectiveTolerance,
-                        property,
-                        attempts: attemptCount,
-                        adjustment_mode: 'semantic',
-                        actual_state: actualState,
-                        converged: true,
-                        within_tolerance: true,
-                        reason: 'control already within tolerance'
-                    },
-                    traceSteps
-                });
-                return {
-                    ...base,
-                    target_state: {
-                        property,
-                        target_value: normalizedTargetValue,
-                        tolerance: effectiveTolerance
-                    },
-                    actual_state: actualState,
-                    within_tolerance: true,
-                    converged: true,
-                    attempts: attemptCount,
-                    adjustment_mode: 'semantic'
-                };
-            }
-            if (!bounds) {
-                return buildFailure('ELEMENT_NOT_INTERACTABLE', 'adjustable control has no bounds', resolvedTarget, currentDevice, actualState, attemptCount, lastAdjustmentMode, false);
-            }
-            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: normalizedTargetValue,
-                    platform: resolvedPlatform,
-                    deviceId: resolvedDeviceId
-                });
-                const observedValue = ToolsInteract._parseNumericControlValue(verification?.observed_state?.value) ??
-                    ToolsInteract._parseNumericControlValue(verification?.observed_state?.raw_value);
-                const observedState = observedValue !== null
-                    ? {
-                        property,
-                        value: observedValue,
-                        raw_value: typeof verification?.observed_state?.raw_value === 'number' ? verification.observed_state.raw_value : undefined
-                    }
-                    : actualState;
-                return {
-                    verification,
-                    observedState,
-                    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 };
-            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 + 1,
-                        mode: 'semantic',
-                        strategy: 'direct_set_value',
-                        target_value: normalizedTargetValue
-                    });
-                    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,
-                            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,
-                            within_tolerance: true,
-                            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
-                    });
-                    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,
-                        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 (attemptCount < attemptsLimit) {
-                coordinateTapsAwaitingFreshGesture = false;
-                lastAdjustmentMode = 'gesture';
-                recordTraceStep('execute', 'retry', {
-                    attempt: attemptCount + 1,
-                    mode: 'gesture',
-                    start: currentPoint,
-                    end: targetPoint
-                });
-                const fallbackActionResult = await ToolsInteract.swipeHandler({
-                    platform: resolvedPlatform,
-                    x1: currentPoint.x,
-                    y1: currentPoint.y,
-                    x2: targetPoint.x,
-                    y2: targetPoint.y,
-                    duration: inferredSliderState ? 520 : 220,
-                    deviceId: resolvedDeviceId
-                });
-                attemptCount++;
-                if (!fallbackActionResult.success) {
-                    recordTraceStep('execute', 'failure', {
-                        attempt: attemptCount,
-                        mode: 'gesture',
-                        start: currentPoint,
-                        end: targetPoint,
-                        success: false
-                    });
-                    return buildFailure('UNKNOWN', fallbackActionResult.error ?? 'adjustment gesture failed', resolvedTarget, fallbackActionResult.device ?? actionDevice, observedState ?? actualState, attemptCount, lastAdjustmentMode, false);
-                }
-                actionDevice = fallbackActionResult.device ?? actionDevice;
-                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 ?? 'gesture 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
-                    };
-                }
-            }
-            verification = verificationResult.verification;
-            lastObservedState = observedState;
-            if (verificationResult.withinTolerance) {
-                recordTraceStep('verify', 'success', {
-                    attempt: attemptCount,
-                    property,
-                    target_value: normalizedTargetValue,
-                    actual_state: observedState,
-                    reason: verification?.reason ?? 'control converged to target value'
-                });
-                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: 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 = 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('CONTROL_CONVERGENCE_FAILED', 'control did not converge within the allotted attempts', resolvedTarget, currentDevice, lastObservedState, attemptCount, lastAdjustmentMode, true, uiFingerprintAfter);
+    static async adjustControlHandler(input) {
+        return adjustControl(input, {
+            observe: (platform, deviceId) => ToolsObserve.getUITreeHandler({ platform, deviceId }),
+            fingerprint: (platform, deviceId) => ToolsInteract._captureFingerprint(platform, deviceId),
+            getHandle: id => ToolsInteract._resolvedUiElements.get(id),
+            currentHandle: (elements, platform, deviceId, handle) => ToolsInteract._findCurrentResolvedElement(elements, platform, deviceId, handle),
+            target: (platform, deviceId, match) => ToolsInteract._resolvedTargetFromElement(ToolsInteract._computeElementId(platform, deviceId, match.el, match.idx), match.el, match.idx),
+            wait: input => ToolsInteract.waitForUIHandler(input), find: input => ToolsInteract.findElementHandler(input),
+            expectState: input => ToolsInteract.expectStateHandler(input), service: (platform, deviceId) => ToolsInteract.getInteractionService(platform, deviceId),
+            tap: input => ToolsInteract.tapHandler(input), swipe: input => ToolsInteract.swipeHandler(input)
+        });
     }
     static async swipeHandler({ platform = 'android', x1, y1, x2, y2, duration, deviceId, timeoutMs }) {
         const { interact, resolved } = await ToolsInteract.getInteractionService(platform, deviceId);
@@ -1779,1446 +167,33 @@ export class ToolsInteract {
         const { interact, resolved } = await ToolsInteract.getInteractionService(platform, deviceId);
         return await interact.scrollToElement(selector, direction, maxScrolls, scrollAmount, resolved.id);
     }
-    static async findElementHandler({ query, exact = false, timeoutMs = 3000, platform, deviceId }) {
-        // Try to use observe layer to fetch the current UI tree and perform a fast semantic search
-        const start = Date.now();
-        const deadline = start + timeoutMs;
-        const normalize = ToolsInteract._normalize;
-        const q = normalize(query);
-        if (!q)
-            return { found: false, error: 'Empty query' };
-        let best = null;
-        let bestTree = null;
-        let bestIterationCandidates = [];
-        let shouldStop = false;
-        const scoreElement = (el, idx) => {
-            if (!el || !el.visible)
-                return null;
-            const bounds = el.bounds || [0, 0, 0, 0];
-            if (!Array.isArray(bounds) || bounds.length < 4)
-                return null;
-            const [l, t, r, b] = bounds;
-            if (r <= l || b <= t)
-                return null;
-            // Do not early-return on non-interactable elements — score them so we can locate their clickable ancestor later
-            const interactable = !!(el.clickable || el.enabled || el.focusable || ToolsInteract._isSemanticActionable(el));
-            const text = normalize(el.text ?? el.label ?? el.value ?? '');
-            const content = normalize(el.contentDescription ?? el.contentDesc ?? el.accessibilityLabel ?? '');
-            const resourceId = normalize(el.resourceId ?? el.resourceID ?? el.id ?? '');
-            const className = normalize(el.type ?? el.class ?? '');
-            const semanticRole = normalize(el.semantic?.semantic_role ?? '');
-            const semanticActions = Array.isArray(el.semantic?.supported_actions) ? el.semantic.supported_actions.map((action) => normalize(action)).filter(Boolean) : [];
-            let score = 0;
-            let reason = 'best_scoring_candidate';
-            if (exact) {
-                if (text && text === q) {
-                    score = 1.0;
-                    reason = 'exact_text_match';
-                }
-                else if (content && content === q) {
-                    score = 0.95;
-                    reason = 'exact_content_desc_match';
-                }
-                else if (resourceId && resourceId === q) {
-                    score = 0.92;
-                    reason = 'exact_resource_id_match';
-                }
-                else if (className && className === q) {
-                    score = 0.3;
-                    reason = 'exact_class_match';
-                }
-            }
-            else {
-                if (text && text === q) {
-                    score = 1.0;
-                    reason = 'exact_text_match';
-                }
-                else if (content && content === q) {
-                    score = 0.95;
-                    reason = 'exact_content_desc_match';
-                }
-                else if (resourceId && resourceId === q) {
-                    score = 0.92;
-                    reason = 'exact_resource_id_match';
-                }
-                else if (text && text.includes(q)) {
-                    score = 0.6;
-                    reason = 'partial_text_match';
-                }
-                else if (content && content.includes(q)) {
-                    score = 0.55;
-                    reason = 'partial_content_desc_match';
-                }
-                else if (resourceId && resourceId.includes(q)) {
-                    score = 0.7;
-                    reason = 'partial_resource_id_match';
-                }
-                else if (className && className.includes(q)) {
-                    score = 0.3;
-                    reason = 'partial_class_match';
-                }
-            }
-            if (!exact) {
-                if (!score && semanticRole && semanticRole.includes(q)) {
-                    score = 0.5;
-                    reason = 'semantic_role_match';
-                }
-                if (semanticActions.some((action) => action.includes(q))) {
-                    score = Math.max(score, score > 0 ? 0.65 : 0.6);
-                    reason = 'semantic_action_match';
-                }
-                if (score === 0 && el.semantic?.adjustable && /slider|stepper|dropdown|segment|control|adjust/.test(q)) {
-                    score = 0.45;
-                    reason = 'semantic_control_match';
-                }
-            }
-            else {
-                if (!score && semanticRole && semanticRole === q) {
-                    score = 0.5;
-                    reason = 'semantic_role_match';
-                }
-                if (semanticActions.some((action) => action === q)) {
-                    score = Math.max(score, score > 0 ? 0.65 : 0.6);
-                    reason = 'semantic_action_match';
-                }
-            }
-            if (score > 0 && interactable)
-                score += 0.05;
-            if (score <= 0)
-                return null;
-            return { el, idx, score, reason, interactable };
-        };
-        while (Date.now() <= deadline) {
-            try {
-                const tree = await ToolsObserve.getUITreeHandler({ platform, deviceId });
-                if (tree && Array.isArray(tree.elements)) {
-                    const elements = tree.elements;
-                    const iterationCandidates = [];
-                    let iterationImprovedBest = false;
-                    for (let i = 0; i < elements.length; i++) {
-                        const el = elements[i];
-                        try {
-                            const candidate = scoreElement(el, i);
-                            if (!candidate)
-                                continue;
-                            iterationCandidates.push(candidate);
-                            if (!best || candidate.score > best.score) {
-                                best = candidate;
-                                bestTree = tree;
-                                iterationImprovedBest = true;
-                                if (best.score >= 0.95) {
-                                    shouldStop = true;
-                                    break;
-                                }
-                            }
-                        }
-                        catch (e) {
-                            checkDebuggerGuard();
-                            console.error('Error scoring element:', e);
-                        }
-                    }
-                    if (iterationImprovedBest) {
-                        bestIterationCandidates = iterationCandidates.slice();
-                    }
-                }
-            }
-            catch (e) {
-                checkDebuggerGuard();
-                console.error('Error fetching UI tree:', e);
-            }
-            if (shouldStop || Date.now() > deadline)
-                break;
-            await new Promise(r => setTimeout(r, 100));
-        }
-        if (!best)
-            return { found: false, error: 'Element not found' };
-        // If the best match is not interactable, try to resolve an actionable ancestor.
-        try {
-            const elements = (bestTree && Array.isArray(bestTree.elements)) ? bestTree.elements : [];
-            const screen = bestTree?.resolution && typeof bestTree.resolution === 'object' ? bestTree.resolution : null;
-            let chosen = best;
-            const childBounds = Array.isArray(chosen?.el?.bounds) ? chosen.el.bounds : null;
-            // Strategy 1: if parentId references an index, climb that chain
-            let resolvedAncestor = null;
-            if (childBounds && (chosen.el.parentId !== undefined && chosen.el.parentId !== null)) {
-                let cur = chosen;
-                let safety = 0;
-                while (cur && safety < 20 && !(cur.el.clickable || cur.el.focusable) && (cur.el.parentId !== undefined && cur.el.parentId !== null)) {
-                    let pid = cur.el.parentId;
-                    let idx = null;
-                    if (typeof pid === 'number')
-                        idx = pid;
-                    else if (typeof pid === 'string' && /^\d+$/.test(pid))
-                        idx = Number(pid);
-                    // If parentId is not an index, try to find by matching resourceId or id field
-                    if (idx !== null && elements[idx]) {
-                        cur = { el: elements[idx], idx };
-                        if (cur && (cur.el.clickable || cur.el.enabled || cur.el.focusable)) {
-                            resolvedAncestor = cur;
-                            break;
-                        }
-                    }
-                    else if (typeof pid === 'string') {
-                        // fallback: search elements for matching resourceId or id
-                        const foundIndex = elements.findIndex((el) => (el.resourceId === pid || el.id === pid));
-                        const found = foundIndex >= 0 ? elements[foundIndex] : null;
-                        if (found) {
-                            cur = { el: found, idx: foundIndex };
-                            if (cur && (cur.el.clickable || cur.el.enabled || cur.el.focusable)) {
-                                resolvedAncestor = cur;
-                                break;
-                            }
-                            // otherwise continue climbing if this found element has its own parentId
-                        }
-                        else {
-                            break;
-                        }
-                    }
-                    else {
-                        break;
-                    }
-                    safety++;
-                }
-            }
-            // Strategy 2: fallback - find a clickable element whose bounds fully contain the child's bounds
-            if (!resolvedAncestor && childBounds) {
-                const [cl, ct, cr, cb] = childBounds;
-                // find candidates that are clickable and contain the child bounds
-                const candidates = elements
-                    .map((el, idx) => ({ el, idx }))
-                    .filter(({ el }) => el && (el.clickable || el.focusable) && Array.isArray(el.bounds) && el.bounds.length >= 4);
-                let bestCandidate = null;
-                let bestCandidateArea = Infinity;
-                for (const c of candidates) {
-                    const bounds = c.el.bounds;
-                    const [pl, pt, pr, pb] = bounds;
-                    if (pl <= cl && pt <= ct && pr >= cr && pb >= cb) {
-                        const area = (pr - pl) * (pb - pt);
-                        if (area < bestCandidateArea) {
-                            bestCandidateArea = area;
-                            bestCandidate = c;
-                        }
-                    }
-                }
-                if (bestCandidate)
-                    resolvedAncestor = bestCandidate;
-            }
-            if (resolvedAncestor) {
-                best = {
-                    el: resolvedAncestor.el,
-                    idx: resolvedAncestor.idx,
-                    score: Math.min(1, best.score + 0.02),
-                    reason: 'clickable_parent_preferred',
-                    interactable: true
-                };
-            }
-            if (best && !(best.el.clickable || best.el.focusable || ToolsInteract._isSemanticActionable(best.el))) {
-                const nearbyActionable = ToolsInteract._resolveNearbyActionableControl(elements, { el: best.el, idx: best.idx }, screen);
-                if (nearbyActionable) {
-                    best = {
-                        el: nearbyActionable.el,
-                        idx: nearbyActionable.idx,
-                        score: Math.min(1, best.score + 0.02),
-                        reason: nearbyActionable.sliderLike ? 'slider_track_preferred' : 'nearby_actionable_control',
-                        interactable: true
-                    };
-                }
-            }
-        }
-        catch (e) {
-            checkDebuggerGuard();
-            console.error('Error resolving ancestor:', e);
-        }
-        if (!best)
-            return { found: false, error: 'Element not found' };
-        const boundsObj = Array.isArray(best.el.bounds) ? { left: best.el.bounds[0], top: best.el.bounds[1], right: best.el.bounds[2], bottom: best.el.bounds[3] } : null;
-        const tapCoordinates = boundsObj ? { x: Math.floor((boundsObj.left + boundsObj.right) / 2), y: Math.floor((boundsObj.top + boundsObj.bottom) / 2) } : null;
-        const uniqueRanked = bestIterationCandidates.filter((candidate, index, array) => index === array.findIndex((other) => other.idx === candidate.idx && other.el === candidate.el));
-        const alternateCandidates = uniqueRanked
-            .filter((candidate) => candidate.idx !== best.idx || candidate.el !== best.el)
-            .slice(0, 3)
-            .map((candidate) => ToolsInteract._summarizeResolutionCandidate(candidate));
-        const outEl = {
-            text: best.el.text ?? null,
-            resourceId: best.el.resourceId ?? null,
-            contentDesc: best.el.contentDescription ?? best.el.contentDesc ?? null,
-            class: best.el.type ?? best.el.class ?? null,
-            bounds: boundsObj,
-            clickable: !!best.el.clickable,
-            enabled: !!best.el.enabled,
-            stable_id: best.el.stable_id ?? null,
-            role: best.el.role ?? null,
-            test_tag: best.el.test_tag ?? null,
-            selector: best.el.selector ?? null,
-            semantic: best.el.semantic ?? null,
-            tapCoordinates,
-            telemetry: {
-                matchedIndex: best.idx ?? null,
-                matchedInteractable: !!best.interactable,
-                sliderLike: best.reason === 'slider_track_preferred'
-            }
-        };
-        if (best.reason === 'slider_track_preferred') {
-            const isVertical = !!boundsObj && (boundsObj.bottom - boundsObj.top) > (boundsObj.right - boundsObj.left);
-            const interactionHint = {
-                kind: 'slider',
-                axis: isVertical ? 'vertical' : 'horizontal',
-                trackBounds: boundsObj
-            };
-            outEl.interactionHint = interactionHint;
-        }
-        const scoreVal = Math.min(1, Number(best.score.toFixed(3)));
-        const resolution = {
-            confidence: scoreVal,
-            reason: best.reason,
-            fallback_available: alternateCandidates.length > 0,
-            matched_count: uniqueRanked.length,
-            alternates: alternateCandidates
-        };
-        return { found: true, element: outEl, score: scoreVal, confidence: scoreVal, resolution };
-    }
-    static async waitForUIHandler({ selector, condition = 'exists', timeout_ms = 60000, poll_interval_ms = 300, match, retry = { max_attempts: 1, backoff_ms: 0 }, platform, deviceId, singleObservation = false, singleAttempt = false, rejectAmbiguous = false, resolveTapTarget = false }) {
-        const readinessTracker = currentReadinessWait();
-        const overallStart = Date.now();
-        const requestedIndex = typeof match?.index === 'number' ? match.index : null;
-        const requested = {
-            selector: selector ?? {},
-            condition,
-            match: requestedIndex === null ? null : { index: requestedIndex }
-        };
-        // Validate selector: require at least one non-empty field (text, resource_id, or accessibility_id)
-        const hasText = typeof selector?.text === 'string' && selector.text.trim().length > 0;
-        const hasResId = typeof selector?.resource_id === 'string' && selector.resource_id.trim().length > 0;
-        const hasAccId = typeof selector?.accessibility_id === 'string' && selector.accessibility_id.trim().length > 0;
-        if (!hasText && !hasResId && !hasAccId) {
-            return {
-                status: 'timeout',
-                error: {
-                    code: 'INVALID_SELECTOR',
-                    message: 'Selector must include at least one non-empty field: text, resource_id, or accessibility_id'
-                },
-                metrics: { latency_ms: Date.now() - overallStart, poll_count: 0, attempts: 0 },
-                requested,
-                observed: { matched_count: 0, condition_satisfied: false, selected_index: null, last_matched_element: null }
-            };
-        }
-        // Validate condition
-        if (!['exists', 'not_exists', 'visible', 'clickable'].includes(condition)) {
-            return { status: 'timeout', error: { code: 'INVALID_CONDITION', message: `Unsupported condition: ${condition}` }, metrics: { latency_ms: Date.now() - overallStart, poll_count: 0, attempts: 0 }, requested, observed: { matched_count: 0, condition_satisfied: false, selected_index: null, last_matched_element: null } };
-        }
-        // Platform check
-        if (platform && !['android', 'ios'].includes(platform)) {
-            return { status: 'timeout', error: { code: 'PLATFORM_NOT_SUPPORTED', message: `Unsupported platform: ${platform}` }, metrics: { latency_ms: Date.now() - overallStart, poll_count: 0, attempts: 0 }, requested, observed: { matched_count: 0, condition_satisfied: false, selected_index: null, last_matched_element: null } };
-        }
-        const effectivePoll = Math.max(50, Math.min(poll_interval_ms || 300, 2000));
-        const maxAttempts = (retry && retry.max_attempts) ? Math.max(1, retry.max_attempts) : 1;
-        const backoff = (retry && retry.backoff_ms) ? Math.max(0, retry.backoff_ms) : 0;
-        let attempts = 0;
-        let totalPollCount = 0;
-        let lastMatchedCount = 0;
-        let lastMatchedElement = null;
-        let lastConditionSatisfied = false;
-        let matchedAt = null;
-        let stableMatchCount = 0;
-        const stableObservationCount = singleObservation ? 1 : 2;
-        const snapshotStaleThresholdMs = 500;
-        // Precompute normalized selector values and helpers (constant across polls)
-        const normalize = ToolsInteract._normalize;
-        const containsFlag = !!selector?.contains;
-        const selText = normalize(selector?.text);
-        const selRid = normalize(selector?.resource_id);
-        const selAid = normalize(selector?.accessibility_id);
-        try {
-            while (attempts < maxAttempts) {
-                attempts++;
-                const attemptStart = Date.now();
-                const deadline = attemptStart + (timeout_ms || 0);
-                while (Date.now() <= deadline || (singleAttempt && totalPollCount === 0)) {
-                    remainingBudget();
-                    totalPollCount++;
-                    try {
-                        const acquisitionStarted = Date.now();
-                        const tree = await ToolsObserve.getUITreeHandler({ platform, deviceId });
-                        observeReadinessWait(tree, acquisitionStarted);
-                        // A failed acquisition cannot establish that the requested tap target is absent.
-                        if (resolveTapTarget && tree?.error && /ACTION_TIMEOUT|timed out/i.test(String(tree.error)))
-                            throw new Error('ACTION_TIMEOUT');
-                        const elements = (tree && Array.isArray(tree.elements)) ? tree.elements : [];
-                        const matches = [];
-                        for (let i = 0; i < elements.length; i++) {
-                            const el = elements[i];
-                            let ok = true;
-                            // text
-                            if (selector.text !== undefined && selector.text !== null) {
-                                const val = normalize(el.text || el.label || el.value || '');
-                                if (containsFlag) {
-                                    if (!val.includes(selText))
-                                        ok = false;
-                                }
-                                else {
-                                    if (val !== selText)
-                                        ok = false;
-                                }
-                            }
-                            // resource_id
-                            if (ok && selector.resource_id !== undefined && selector.resource_id !== null) {
-                                const rid = normalize(el.resourceId || el.resourceID || el.id || '');
-                                if (containsFlag) {
-                                    if (!rid.includes(selRid))
-                                        ok = false;
-                                }
-                                else {
-                                    if (rid !== selRid)
-                                        ok = false;
-                                }
-                            }
-                            // accessibility_id
-                            if (ok && selector.accessibility_id !== undefined && selector.accessibility_id !== null) {
-                                const aid = normalize(el.contentDescription || el.contentDesc || el.accessibilityLabel || el.label || '');
-                                if (containsFlag) {
-                                    if (!aid.includes(selAid))
-                                        ok = false;
-                                }
-                                else {
-                                    if (aid !== selAid)
-                                        ok = false;
-                                }
-                            }
-                            if (ok)
-                                matches.push({ el, idx: i });
-                        }
-                        // Evaluate condition
-                        const matchedCount = matches.length;
-                        if (rejectAmbiguous && matchedCount > 1 && match?.index === undefined)
-                            return { status: 'timeout', error: { code: 'AMBIGUOUS_TARGET' } };
-                        const pickIndex = (typeof match?.index === 'number') ? match.index : undefined;
-                        let chosen = null;
-                        if (matches.length > 0) {
-                            if (pickIndex !== undefined) {
-                                // If a specific index is requested but out of bounds, treat as not matched for this poll (deterministic)
-                                if (pickIndex >= 0 && pickIndex < matches.length)
-                                    chosen = matches[pickIndex];
-                                else
-                                    chosen = null;
-                            }
-                            else {
-                                chosen = matches[0];
-                            }
-                        }
-                        else {
-                            chosen = null;
-                        }
-                        let conditionMet = false;
-                        let matchedElement = chosen;
-                        if (condition === 'exists') {
-                            // when an index is specified, existence requires that specific index be present
-                            conditionMet = (pickIndex !== undefined) ? (chosen !== null) : (matchedCount >= 1);
-                        }
-                        else if (condition === 'not_exists') {
-                            // when an index is specified, not_exists is true if that index is absent
-                            conditionMet = (pickIndex !== undefined) ? (chosen === null) : (matchedCount === 0);
-                        }
-                        else if (condition === 'visible') {
-                            if (chosen) {
-                                const b = chosen.el.bounds;
-                                const visibleFlag = !!chosen.el.visible && Array.isArray(b) && b.length >= 4 && (b[2] > b[0] && b[3] > b[1]);
-                                conditionMet = visibleFlag;
-                            }
-                            else
-                                conditionMet = false;
-                        }
-                        else if (condition === 'clickable') {
-                            matchedElement = chosen ? (resolveTapTarget && (!ToolsInteract._isVisibleElement(chosen.el) || chosen.el.enabled === false)
-                                ? chosen : ToolsInteract._resolveActionableAncestor(elements, chosen) || chosen) : null;
-                            if (matchedElement) {
-                                const b = matchedElement.el.bounds;
-                                const visibleFlag = !!matchedElement.el.visible && Array.isArray(b) && b.length >= 4 && (b[2] > b[0] && b[3] > b[1]);
-                                const enabled = !!matchedElement.el.enabled;
-                                const clickable = !!matchedElement.el.clickable || !!matchedElement.el._interactable || !!matchedElement.el.focusable;
-                                conditionMet = visibleFlag && enabled && clickable;
-                            }
-                            else
-                                conditionMet = false;
-                        }
-                        // Waiting for a label to exist/be visible is distinct from resolving its
-                        // executable control. Reuse the clickable-wait ancestor policy without
-                        // promoting hidden or disabled labels into an unrelated enabled target.
-                        if (resolveTapTarget && conditionMet && matchedElement &&
-                            ToolsInteract._isVisibleElement(matchedElement.el) && matchedElement.el.enabled !== false) {
-                            matchedElement = ToolsInteract._resolveActionableAncestor(elements, matchedElement) ?? matchedElement;
-                        }
-                        const resolvedPlatform = tree?.device?.platform === 'ios' ? 'ios' : (platform || 'android');
-                        const resolvedDeviceId = tree?.device?.id || deviceId;
-                        lastMatchedCount = matchedCount;
-                        lastConditionSatisfied = conditionMet;
-                        lastMatchedElement = matchedElement ? ToolsInteract._buildResolvedElement(resolvedPlatform, resolvedDeviceId, matchedElement.el, matchedElement.idx) : null;
-                        const now = Date.now();
-                        const snapshotAgeMs = typeof tree?.captured_at_ms === 'number' ? now - tree.captured_at_ms : null;
-                        const snapshotFresh = snapshotAgeMs === null || snapshotAgeMs <= snapshotStaleThresholdMs;
-                        if (conditionMet && snapshotFresh) {
-                            if (matchedAt === null)
-                                matchedAt = now;
-                            stableMatchCount++;
-                            if (stableMatchCount >= stableObservationCount && (!readinessTracker || readinessTracker.summary.state === 'settled')) {
-                                const latency_ms = now - overallStart;
-                                const outEl = lastMatchedElement;
-                                return {
-                                    status: 'success',
-                                    ...(singleObservation ? { _tree: tree } : {}),
-                                    matched: matchedCount,
-                                    element: outEl,
-                                    metrics: { latency_ms, poll_count: totalPollCount, attempts },
-                                    requested,
-                                    observed: {
-                                        matched_count: matchedCount,
-                                        condition_satisfied: true,
-                                        selected_index: outEl?.index ?? null,
-                                        last_matched_element: outEl
-                                    }
-                                };
-                            }
-                        }
-                        else {
-                            stableMatchCount = 0;
-                            matchedAt = null;
-                        }
-                    }
-                    catch (e) {
-                        checkDebuggerGuard();
-                        // Deadline expiry does not invalidate the last successfully observed state.
-                        if (e instanceof Error && e.message === 'ACTION_TIMEOUT')
-                            throw e;
-                        if (readinessTracker && !String(e).includes('READINESS_'))
-                            readinessTracker.unavailable();
-                        if (readinessTracker && isDeviceUnavailable(e))
-                            throw e;
-                        // Non-fatal per-poll error; record and continue
-                        if (!readinessTracker)
-                            console.warn('waitForUI: poll error (non-fatal):', e instanceof Error ? e.message : String(e));
-                    }
-                    if (singleAttempt)
-                        break;
-                    // Sleep until next poll
-                    await (readinessTracker ? readinessDelay(effectivePoll || 50) : new Promise(r => setTimeout(r, effectivePoll || 50)));
-                }
-                // Attempt timed out; if more attempts allowed, backoff then retry
-                if (attempts < maxAttempts) {
-                    if (backoff > 0)
-                        await (readinessTracker ? readinessDelay(backoff) : new Promise(r => setTimeout(r, backoff)));
-                    continue;
-                }
-                // Final failure for this call
-                const elapsed = Date.now() - overallStart;
-                const observed = {
-                    matched_count: lastMatchedCount,
-                    condition_satisfied: lastConditionSatisfied,
-                    selected_index: lastMatchedElement?.index ?? null,
-                    last_matched_element: lastMatchedElement
-                };
-                const matchNote = requestedIndex !== null && lastMatchedCount <= requestedIndex
-                    ? ` requested match.index=${requestedIndex} but observed ${lastMatchedCount} match(es)`
-                    : ` observed ${lastMatchedCount} match(es)`;
-                return {
-                    status: 'timeout',
-                    error: { code: readinessTracker ? 'TIMEOUT' : 'ELEMENT_NOT_FOUND', message: `Condition ${condition} not satisfied within timeout;${matchNote}` },
-                    metrics: { latency_ms: elapsed, poll_count: totalPollCount, attempts },
-                    requested,
-                    observed
-                };
-            }
-        }
-        catch (err) {
-            checkDebuggerGuard();
-            if (!readinessTracker && err instanceof Error && err.message === 'ACTION_TIMEOUT')
-                throw err;
-            if (readinessTracker && isDeviceUnavailable(err))
-                throw err;
-            const elapsed = Date.now() - overallStart;
-            return {
-                status: 'timeout',
-                error: { code: readinessTracker && String(err).includes('ACTION_TIMEOUT') ? 'TIMEOUT' : 'INTERNAL_ERROR', message: readinessTracker ? 'Readiness predicate wait did not complete' : err instanceof Error ? err.message : String(err) },
-                metrics: { latency_ms: elapsed, poll_count: totalPollCount, attempts },
-                requested,
-                observed: {
-                    matched_count: lastMatchedCount,
-                    condition_satisfied: readinessTracker ? lastConditionSatisfied : false,
-                    selected_index: lastMatchedElement?.index ?? null,
-                    last_matched_element: lastMatchedElement
-                }
-            };
-        }
+    static async findElementHandler(input) {
+        return findElement(input, target => ToolsObserve.getUITreeHandler(target));
     }
-    // Helper: normalize various log objects into plain message strings for comparison
-    static _logsToMessages(logsArr) {
-        if (!Array.isArray(logsArr))
-            return [];
-        return logsArr.map((l) => {
-            if (typeof l === 'string')
-                return l;
-            if (l && (l.message || l.msg))
-                return l.message || l.msg;
-            try {
-                return JSON.stringify(l);
-            }
-            catch {
-                return String(l);
-            }
-        });
+    static async waitForUIHandler(input) {
+        return waitForUI(input, { observe: target => ToolsObserve.getUITreeHandler(target),
+            resolve: (platform, deviceId, element, index) => ToolsInteract._buildResolvedElement(platform, deviceId, element, index) });
     }
-    static async waitForScreenChangeHandler({ platform, previousFingerprint, timeoutMs = 5000, pollIntervalMs = 300, deviceId }) {
-        const start = Date.now();
-        let lastFingerprint = null;
-        let lastActivity = null;
-        while (Date.now() - start < timeoutMs) {
-            try {
-                const res = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId });
-                const fp = res?.fingerprint ?? null;
-                lastActivity = res?.activity ?? lastActivity;
-                if (fp === null || fp === undefined) {
-                    lastFingerprint = null;
-                    await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
-                    continue;
-                }
-                lastFingerprint = fp;
-                if (fp !== previousFingerprint) {
-                    // Stability confirmation
-                    await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
-                    try {
-                        const confirmRes = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId });
-                        const confirmFp = confirmRes?.fingerprint ?? null;
-                        lastActivity = confirmRes?.activity ?? lastActivity;
-                        if (confirmFp === fp) {
-                            return {
-                                success: true,
-                                previousFingerprint,
-                                newFingerprint: fp,
-                                elapsedMs: Date.now() - start,
-                                observed_screen: {
-                                    fingerprint: fp,
-                                    activity: lastActivity
-                                }
-                            };
-                        }
-                        lastFingerprint = confirmFp;
-                        continue;
-                    }
-                    catch (e) {
-                        checkDebuggerGuard();
-                        console.error('Error confirming fingerprint:', e);
-                        continue;
-                    }
-                }
-            }
-            catch (e) {
-                checkDebuggerGuard();
-                console.error('Error getting screen fingerprint:', e);
-            }
-            await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
-        }
-        return {
-            success: false,
-            reason: 'timeout',
-            previousFingerprint,
-            lastFingerprint,
-            elapsedMs: Date.now() - start,
-            observed_screen: {
-                fingerprint: lastFingerprint,
-                activity: lastActivity
-            }
-        };
+    static async waitForScreenChangeHandler(input) {
+        return waitForScreenChange(input, { fingerprint: target => ToolsObserve.getScreenFingerprintHandler(target) });
     }
-    static async waitForUIChangeHandler({ platform, deviceId, timeout_ms = 60000, stability_window_ms = 300, expected_change, scope = 'screen', target = null }) {
-        const readinessTracker = currentReadinessWait();
-        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 {
-                if (readinessTracker)
-                    remainingBudget();
-                const acquisitionStarted = Date.now();
-                const tree = await ToolsObserve.getUITreeHandler({ platform, deviceId });
-                observeReadinessWait(tree, acquisitionStarted);
-                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);
-                    if (observedChange) {
-                        if (!candidateSignatures || !ToolsInteract._uiChangeSignaturesEqual(candidateSignatures, signatures) || candidateObservedChange !== observedChange) {
-                            candidateSignatures = signatures;
-                            candidateObservedChange = observedChange;
-                            candidateSinceMs = Date.now();
-                        }
-                        const stableForMs = candidateSinceMs === null ? 0 : Date.now() - candidateSinceMs;
-                        if ((stabilityWindow === 0 || stableForMs >= stabilityWindow) && (!readinessTracker || readinessTracker.summary.state === 'settled')) {
-                            return {
-                                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'
-                            };
-                        }
-                    }
-                    else {
-                        candidateSignatures = null;
-                        candidateObservedChange = null;
-                        candidateSinceMs = null;
-                    }
-                }
-            }
-            catch (error) {
-                checkDebuggerGuard();
-                if (readinessTracker && !String(error).includes('READINESS_'))
-                    readinessTracker.unavailable();
-                if (readinessTracker && isDeviceUnavailable(error))
-                    throw error;
-                if (readinessTracker && String(error).includes('ACTION_TIMEOUT')) {
-                    readinessTracker.deadline();
-                    break;
-                }
-                // Default waits retain best-effort polling.
-            }
-            await (readinessTracker ? readinessDelay(pollIntervalMs) : new Promise(resolve => setTimeout(resolve, pollIntervalMs)));
-        }
-        return {
-            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'
-        };
+    static async waitForUIChangeHandler(input) {
+        return waitForUIChange(input, { observe: target => ToolsObserve.getUITreeHandler(target), scope: (tree, scope, target) => ToolsInteract._resolveUiChangeScope(tree, scope, target) });
     }
-    static async expectScreenHandler({ platform, fingerprint, screen, deviceId }) {
-        const observedFingerprint = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId });
-        const observedScreen = {
-            fingerprint: observedFingerprint?.fingerprint ?? null,
-            screen: observedFingerprint?.activity ?? null
-        };
-        let observedScreenLabel = observedScreen.screen;
-        if (!fingerprint && screen && platform !== 'ios') {
-            try {
-                const current = await ToolsObserve.getCurrentScreenHandler({ deviceId });
-                observedScreenLabel = current?.shortActivity || current?.activity || observedScreenLabel;
-            }
-            catch {
-                // Keep fingerprint-derived activity when current-screen lookup is unavailable.
-            }
-        }
-        const expectedScreen = {
-            fingerprint: fingerprint ?? null,
-            screen: screen ?? null
-        };
-        let success = false;
-        let basis = 'none';
-        let reason = 'No fingerprint or screen expectation provided';
-        if (fingerprint) {
-            basis = 'fingerprint';
-            success = observedScreen.fingerprint === fingerprint;
-            reason = success
-                ? `observed fingerprint matches expected fingerprint ${fingerprint}`
-                : `expected fingerprint ${fingerprint} but observed ${observedScreen.fingerprint ?? 'null'}`;
-        }
-        else if (screen) {
-            basis = 'screen';
-            const candidates = new Set();
-            if (observedScreen.screen)
-                candidates.add(observedScreen.screen);
-            if (observedScreenLabel)
-                candidates.add(observedScreenLabel);
-            success = candidates.has(screen);
-            reason = success
-                ? `observed screen matches expected screen ${screen}`
-                : `expected screen ${screen} but observed ${observedScreenLabel ?? observedScreen.screen ?? 'null'}`;
-        }
-        return {
-            success,
-            observed_screen: {
-                fingerprint: observedScreen.fingerprint,
-                screen: observedScreenLabel
-            },
-            expected_screen: expectedScreen,
-            confidence: success ? 1 : 0,
-            comparison: {
-                basis,
-                matched: success,
-                reason
-            },
-            trace: buildObservationTrace({
-                actionType: 'expect_screen',
-                stage: 'verify',
-                success,
-                attempts: 1,
-                metadata: {
-                    expected_screen: expectedScreen,
-                    observed_screen: {
-                        fingerprint: observedScreen.fingerprint,
-                        screen: observedScreenLabel
-                    },
-                    comparison: {
-                        basis,
-                        matched: success
-                    }
-                }
-            })
-        };
+    static async expectScreenHandler(input) {
+        return expectScreen(input, { fingerprint: target => ToolsObserve.getScreenFingerprintHandler(target), current: target => ToolsObserve.getCurrentScreenHandler(target) });
     }
-    static async expectElementVisibleHandler({ selector, element_id, timeout_ms = 5000, poll_interval_ms = 300, platform, deviceId }) {
-        const result = await ToolsInteract.waitForUIHandler({
-            selector,
-            condition: 'visible',
-            timeout_ms,
-            poll_interval_ms,
-            platform,
-            deviceId
-        });
-        if (result?.status === 'success' && result?.element) {
-            return {
-                success: true,
-                selector,
-                element_id: result.element.elementId ?? element_id ?? null,
-                expected_condition: 'visible',
-                element: {
-                    elementId: result.element.elementId ?? null,
-                    text: result.element.text ?? null,
-                    resource_id: result.element.resource_id ?? null,
-                    accessibility_id: result.element.accessibility_id ?? null,
-                    class: result.element.class ?? null,
-                    bounds: result.element.bounds ?? null,
-                    index: typeof result.element.index === 'number' ? result.element.index : null,
-                    state: result.element.state ?? null,
-                    stable_id: result.element.stable_id ?? null,
-                    role: result.element.role ?? null,
-                    test_tag: result.element.test_tag ?? null,
-                    selector: result.element.selector ?? null,
-                    semantic: result.element.semantic ?? null
-                },
-                observed: {
-                    status: result.status,
-                    matched_count: typeof result.matched === 'number' ? result.matched : result?.observed?.matched_count ?? null,
-                    condition_satisfied: true,
-                    selected_index: typeof result.element.index === 'number' ? result.element.index : null,
-                    last_matched_element: {
-                        elementId: result.element.elementId ?? null,
-                        text: result.element.text ?? null,
-                        resource_id: result.element.resource_id ?? null,
-                        accessibility_id: result.element.accessibility_id ?? null,
-                        class: result.element.class ?? null,
-                        bounds: result.element.bounds ?? null,
-                        index: typeof result.element.index === 'number' ? result.element.index : null,
-                        state: result.element.state ?? null,
-                        stable_id: result.element.stable_id ?? null,
-                        role: result.element.role ?? null,
-                        test_tag: result.element.test_tag ?? null,
-                        selector: result.element.selector ?? null,
-                        semantic: result.element.semantic ?? null
-                    }
-                },
-                reason: 'selector is visible',
-                trace: buildObservationTrace({
-                    actionType: 'expect_element_visible',
-                    stage: 'verify',
-                    success: true,
-                    attempts: 1,
-                    metadata: {
-                        selector,
-                        element_id: result.element.elementId ?? element_id ?? null,
-                        status: result.status
-                    }
-                })
-            };
-        }
-        const errorCode = result?.error?.code === 'INTERNAL_ERROR' ? 'UNKNOWN' : 'TIMEOUT';
-        return {
-            success: false,
-            selector,
-            element_id: element_id ?? null,
-            expected_condition: 'visible',
-            observed: {
-                status: result?.status,
-                matched_count: result?.observed?.matched_count,
-                condition_satisfied: result?.observed?.condition_satisfied ?? false,
-                selected_index: result?.observed?.selected_index ?? null,
-                last_matched_element: result?.observed?.last_matched_element ?? null
-            },
-            reason: result?.error?.message ?? 'selector is not visible',
-            failure_code: errorCode,
-            retryable: errorCode === 'TIMEOUT',
-            trace: buildObservationTrace({
-                actionType: 'expect_element_visible',
-                stage: 'verify',
-                success: false,
-                attempts: 1,
-                metadata: {
-                    selector,
-                    element_id: element_id ?? null,
-                    status: result?.status ?? null,
-                    reason: result?.error?.message ?? 'selector is not visible'
-                }
-            })
-        };
+    static async expectElementVisibleHandler(input) {
+        return expectVisible(input, request => ToolsInteract.waitForUIHandler(request));
     }
-    static async expectStateHandler({ selector, element_id, property, expected, platform, deviceId, stabilization_window_ms = 1000, stable_observation_count = 2, snapshot_stale_threshold_ms = 500, poll_interval_ms = 150, exact_budget = false }) {
-        const compareBoolean = (value) => typeof value === 'boolean' ? value : null;
-        const compareString = (value) => typeof value === 'string' ? value : null;
-        const compareNumber = (value) => typeof value === 'number' && Number.isFinite(value) ? value : null;
-        const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
-        const start = Date.now();
-        const deadline = start + (exact_budget ? stabilization_window_ms : Math.max(500, stabilization_window_ms));
-        const stableTarget = Math.max(1, Math.floor(stable_observation_count || 2));
-        const pollDelay = exact_budget ? Math.max(50, Math.min(poll_interval_ms || 150, 1000)) : Math.max(100, Math.min(poll_interval_ms || 150, 200));
-        const staleThreshold = Math.max(300, Math.min(snapshot_stale_threshold_ms || 500, 800));
-        let attempts = 0;
-        let stableCount = 0;
-        let lastReason = 'element not found';
-        let lastFailureCode = 'ELEMENT_NOT_FOUND';
-        let lastObservedElement = null;
-        let lastObservedValue = null;
-        let lastRawValue = null;
-        let lastResolvedElementId = element_id ?? null;
-        const traceSteps = [];
-        let traceAttemptIndex = 0;
-        let resolveRecorded = false;
-        const recordTraceStep = (stage, result, metadata) => {
-            traceSteps.push(createTraceStep({
-                stage,
-                timestamp: Date.now(),
-                result,
-                attemptIndex: traceAttemptIndex++,
-                metadata
-            }));
-        };
-        const buildStateTrace = (outcome) => ({
-            action_id: nextActionId('expect_state', Date.now()),
-            steps: traceSteps,
-            final_outcome: outcome,
-            attempts
-        });
-        while (Date.now() <= deadline) {
-            attempts++;
-            const tree = await ToolsObserve.getUITreeHandler({ platform, deviceId });
-            const elements = Array.isArray(tree?.elements) ? tree.elements : [];
-            const treePlatform = tree?.device?.platform === 'ios' ? 'ios' : (platform || 'android');
-            const treeDeviceId = tree?.device?.id || deviceId;
-            const treeAgeMs = typeof tree?.captured_at_ms === 'number' ? Date.now() - tree.captured_at_ms : null;
-            let matched = null;
-            if (element_id) {
-                const resolved = ToolsInteract._resolvedUiElements.get(element_id);
-                if (resolved) {
-                    const current = ToolsInteract._findCurrentResolvedElement(elements, treePlatform, treeDeviceId, resolved);
-                    if (current)
-                        matched = { el: current.el, idx: current.index };
-                }
-            }
-            if (!matched && selector) {
-                matched = ToolsInteract._findFirstMatchingElement(elements, selector);
-            }
-            if (!matched) {
-                lastReason = 'element not found';
-                lastFailureCode = 'ELEMENT_NOT_FOUND';
-                stableCount = 0;
-                recordTraceStep('resolve', 'retry', {
-                    selector: selector ?? null,
-                    element_id: lastResolvedElementId,
-                    matched: false,
-                    reason: lastReason,
-                    attempt: attempts
-                });
-                recordTraceStep('stabilize', 'retry', {
-                    stabilization_attempts: attempts,
-                    stable_observation_count: stableCount,
-                    snapshot_freshness_ms: treeAgeMs,
-                    reason: lastReason
-                });
-                await sleep(pollDelay);
-                continue;
-            }
-            const resolvedElement = ToolsInteract._resolvedTargetFromElement(ToolsInteract._computeElementId(treePlatform, treeDeviceId, matched.el, matched.idx), matched.el, matched.idx);
-            lastResolvedElementId = resolvedElement.elementId;
-            lastObservedElement = { ...resolvedElement, state: matched.el.state ?? null };
-            if (treeAgeMs !== null && treeAgeMs > staleThreshold) {
-                lastReason = 'stale snapshot';
-                lastFailureCode = 'UNKNOWN';
-                stableCount = 0;
-                recordTraceStep('resolve', 'retry', {
-                    selector: selector ?? null,
-                    element_id: lastResolvedElementId,
-                    matched: true,
-                    reason: lastReason,
-                    attempt: attempts
-                });
-                recordTraceStep('stabilize', 'retry', {
-                    stabilization_attempts: attempts,
-                    stable_observation_count: stableCount,
-                    snapshot_freshness_ms: treeAgeMs,
-                    reason: lastReason
-                });
-                await sleep(pollDelay);
-                continue;
-            }
-            if (!resolveRecorded) {
-                recordTraceStep('resolve', 'success', {
-                    selector: selector ?? null,
-                    element_id: lastResolvedElementId,
-                    matched: true,
-                    reason: 'element resolved'
-                });
-                resolveRecorded = true;
-            }
-            const observedState = matched.el.state ?? null;
-            const actual = observedState?.[property] ?? null;
-            let success = false;
-            let reason = '';
-            let rawValue = null;
-            let observedValue = actual;
-            switch (property) {
-                case 'checked':
-                case 'focused':
-                case 'expanded':
-                case 'enabled': {
-                    const expectedBool = compareBoolean(expected);
-                    const actualBool = compareBoolean(actual);
-                    if (expectedBool === null) {
-                        reason = `expected ${property} must be boolean`;
-                    }
-                    else if (actualBool === null) {
-                        reason = `${property} state unavailable`;
-                    }
-                    else {
-                        rawValue = actualBool;
-                        success = actualBool === expectedBool;
-                        reason = success ? `${property} matches expected value` : `expected ${property}=${expectedBool} but observed ${actualBool}`;
-                    }
-                    observedValue = actualBool;
-                    break;
-                }
-                case 'value':
-                case 'raw_value': {
-                    const expectedNumber = compareNumber(expected);
-                    const actualNumber = compareNumber(actual);
-                    if (expectedNumber !== null && actualNumber !== null) {
-                        success = actualNumber === expectedNumber;
-                        rawValue = actualNumber;
-                        observedValue = actualNumber;
-                        reason = success ? 'value matches expected value' : `expected value=${expectedNumber} but observed ${actualNumber}`;
-                        break;
-                    }
-                    const expectedString = typeof expected === 'string' ? expected : null;
-                    const actualString = compareString(actual);
-                    if (expectedString !== null && actualString !== null) {
-                        success = actualString === expectedString;
-                        rawValue = actualString;
-                        observedValue = actualString;
-                        reason = success ? 'value matches expected value' : `expected value=${expectedString} but observed ${actualString}`;
-                    }
-                    else {
-                        reason = 'value state unavailable';
-                    }
-                    break;
-                }
-                case 'selected': {
-                    const expectedBool = typeof expected === 'boolean' ? expected : null;
-                    const expectedString = typeof expected === 'string'
-                        ? expected
-                        : expected && typeof expected === 'object'
-                            ? String(expected.id ?? expected.label ?? '')
-                            : null;
-                    if (!observedState || observedState.selected === undefined || observedState.selected === null) {
-                        reason = 'selected state unavailable';
-                        break;
-                    }
-                    if (expectedBool !== null) {
-                        const actualBool = typeof observedState.selected === 'boolean' ? observedState.selected : null;
-                        if (actualBool === null) {
-                            reason = 'selected state is not boolean';
-                            break;
-                        }
-                        rawValue = actualBool;
-                        observedValue = actualBool;
-                        success = actualBool === expectedBool;
-                        reason = success ? 'selected matches expected value' : `expected selected=${expectedBool} but observed ${actualBool}`;
-                        break;
-                    }
-                    const actualSelected = typeof observedState.selected === 'object' && observedState.selected !== null
-                        ? String(observedState.selected.id ?? observedState.selected.label ?? '')
-                        : String(observedState.selected);
-                    const actualString = actualSelected.trim();
-                    if (!expectedString) {
-                        reason = 'expected selected must be boolean, string, or object with id/label';
-                        break;
-                    }
-                    rawValue = actualString;
-                    observedValue = actualString;
-                    success = actualString === expectedString;
-                    reason = success ? 'selected matches expected value' : `expected selected=${expectedString} but observed ${actualString}`;
-                    break;
-                }
-                case 'text_value': {
-                    const expectedString = typeof expected === 'string' ? expected : null;
-                    const actualString = compareString(actual);
-                    if (!expectedString) {
-                        reason = 'expected text_value must be string';
-                    }
-                    else if (!actualString) {
-                        reason = 'text_value state unavailable';
-                    }
-                    else {
-                        success = actualString === expectedString;
-                        rawValue = actualString;
-                        observedValue = actualString;
-                        reason = success ? 'text_value matches expected value' : `expected text_value=${expectedString} but observed ${actualString}`;
-                    }
-                    break;
-                }
-                default: {
-                    if (actual !== null && actual !== undefined) {
-                        success = actual === expected;
-                        observedValue = actual;
-                        rawValue = typeof actual === 'string' || typeof actual === 'number' || typeof actual === 'boolean' ? actual : null;
-                        reason = success ? `${property} matches expected value` : `expected ${property} to match but observed ${String(actual)}`;
-                    }
-                    else {
-                        reason = `unsupported or unavailable state property: ${property}`;
-                    }
-                }
-            }
-            if (success) {
-                stableCount++;
-                recordTraceStep('stabilize', 'success', {
-                    stabilization_attempts: attempts,
-                    stable_observation_count: stableCount,
-                    snapshot_freshness_ms: treeAgeMs,
-                    reason
-                });
-                recordTraceStep('verify', 'success', {
-                    property,
-                    expected,
-                    observed_value: observedValue,
-                    reason
-                });
-                if (stableCount >= stableTarget) {
-                    return {
-                        success: true,
-                        selector,
-                        element_id: lastResolvedElementId,
-                        expected_state: { property, expected },
-                        element: lastObservedElement,
-                        observed_state: {
-                            property,
-                            value: observedValue,
-                            ...(rawValue !== null ? { raw_value: rawValue } : {})
-                        },
-                        reason,
-                        stabilization_attempts: attempts,
-                        stabilization_window_ms: Date.now() - start,
-                        stable_observation_count: stableCount,
-                        snapshot_freshness_ms: treeAgeMs ?? undefined,
-                        trace: buildStateTrace('success')
-                    };
-                }
-            }
-            else {
-                stableCount = 0;
-                lastReason = reason || lastReason;
-                lastFailureCode = 'UNKNOWN';
-                recordTraceStep('stabilize', 'retry', {
-                    stabilization_attempts: attempts,
-                    stable_observation_count: stableCount,
-                    snapshot_freshness_ms: treeAgeMs,
-                    reason: lastReason
-                });
-                recordTraceStep('verify', 'retry', {
-                    property,
-                    expected,
-                    observed_value: observedValue,
-                    reason: lastReason
-                });
-            }
-            if (!success) {
-                lastObservedValue = observedValue;
-                lastRawValue = rawValue;
-            }
-            await sleep(pollDelay);
-        }
-        return {
-            success: false,
-            selector,
-            element_id: lastResolvedElementId,
-            expected_state: { property, expected },
-            element: lastObservedElement,
-            observed_state: {
-                property,
-                value: lastObservedValue,
-                ...(lastRawValue !== null ? { raw_value: lastRawValue } : {})
-            },
-            reason: lastReason,
-            failure_code: lastFailureCode,
-            retryable: true,
-            trace: buildStateTrace('failure')
-        };
+    static async expectStateHandler(input) {
+        return expectState(input, { observe: target => ToolsObserve.getUITreeHandler(target), getHandle: id => ToolsInteract._resolvedUiElements.get(id),
+            currentHandle: (elements, platform, deviceId, handle) => ToolsInteract._findCurrentResolvedElement(elements, platform, deviceId, handle),
+            target: (platform, deviceId, match) => ToolsInteract._resolvedTargetFromElement(ToolsInteract._computeElementId(platform, deviceId, match.el, match.idx), match.el, match.idx) });
     }
-    static async waitForUICore({ type = 'ui', query, timeoutMs = 30000, pollIntervalMs = 300, includeSnapshotOnFailure = true, match = 'present', stability_ms = 700, observationDelayMs = 0, platform, deviceId }) {
-        const start = Date.now();
-        const deadline = start + (timeoutMs || 0);
-        const q = (query === null || query === undefined) ? '' : String(query);
-        // Clamp polling interval to 250-500ms for consistent behavior
-        const pollInterval = Math.max(250, Math.min(pollIntervalMs || 300, 500));
-        // Baseline state (fetch in parallel but bound to short timeouts so observation starts promptly)
-        let initialFingerprint = null;
-        let baselineLastLine = null;
-        try {
-            const fpPromise = ToolsObserve.getScreenFingerprintHandler({ platform, deviceId });
-            const logsPromise = ToolsObserve.getLogsHandler({ platform, deviceId, lines: 200 });
-            const withTimeout = (p, ms) => Promise.race([p, new Promise(resolve => setTimeout(() => resolve(null), ms))]);
-            const [fpRes, gl] = await Promise.all([withTimeout(fpPromise, 300), withTimeout(logsPromise, 500)]);
-            if (fpRes && typeof fpRes === 'object')
-                initialFingerprint = fpRes.fingerprint ?? null;
-            if (gl) {
-                const logsArr = Array.isArray(gl.logs) ? gl.logs : [];
-                // Normalize to last message string for baseline comparison
-                const msgs = ToolsInteract._logsToMessages(logsArr);
-                baselineLastLine = msgs.length ? msgs[msgs.length - 1] : null;
-            }
-        }
-        catch (err) {
-            checkDebuggerGuard();
-            try {
-                console.warn('waitForUI: failed to get baseline data (non-fatal):', err instanceof Error ? err.message : String(err));
-            }
-            catch { }
-        }
-        // Network-based waiting removed. Rely on UI and screen fingerprints for determinism.
-        let lastChangeAt = Date.now();
-        let prevFingerprint = initialFingerprint;
-        const sleep = (ms) => new Promise(r => setTimeout(r, ms));
-        // Optional initial observation delay requested by caller
-        if (typeof observationDelayMs === 'number' && observationDelayMs > 0) {
-            try {
-                console.log(`waitForUI: delaying observation for ${observationDelayMs}ms`);
-            }
-            catch { }
-            await sleep(observationDelayMs);
-        }
-        // Telemetry
-        let pollCount = 0;
-        let matchedAt = null;
-        let lastObservedState = null;
-        let stableDuration = 0;
-        let matchSource = null;
-        while (Date.now() <= deadline) {
-            pollCount++;
-            const now = Date.now();
-            // Evaluate condition per type
-            if (type === 'ui') {
-                try {
-                    // Prefer using the public findElementHandler which tests can override. This avoids relying
-                    // on resolveObserve/getUITree for unit tests which may not have devices available.
-                    try {
-                        const findRes = await ToolsInteract.findElementHandler({ query: q, exact: false, timeoutMs: Math.min(500, pollInterval), platform, deviceId });
-                        const isPresent = !!(findRes && findRes.found);
-                        const conditionTrue = (match === 'present') ? isPresent : !isPresent;
-                        if (conditionTrue) {
-                            if (matchedAt === null)
-                                matchedAt = Date.now();
-                            stableDuration = Date.now() - matchedAt;
-                            lastObservedState = true;
-                            if (stableDuration >= stability_ms) {
-                                matchSource = 'ui-find';
-                                const element = isPresent ? findRes.element : null;
-                                const now2 = Date.now();
-                                return { success: true, condition: match, query: q, poll_count: pollCount, duration_ms: now2 - start, stable_duration_ms: stableDuration, matchedElement: element, matchSource, timestamp: now2, type: 'ui', observed_state: lastObservedState ?? null };
-                            }
-                        }
-                        else {
-                            matchedAt = null;
-                            stableDuration = 0;
-                            lastObservedState = false;
-                        }
-                    }
-                    catch (err) {
-                        checkDebuggerGuard();
-                        console.error('waitForUI(ui) find error:', err);
-                    }
-                }
-                catch (err) {
-                    checkDebuggerGuard();
-                    console.error('waitForUI(ui) outer error:', err);
-                }
-            }
-            else if (type === 'log') {
-                try {
-                    // Logs: presence semantics only (match 'present'). Stability not applicable (immediate)
-                    const stream = await ToolsObserve.readLogStreamHandler({ platform, sessionId: 'default', limit: 200 });
-                    const entries = (stream && Array.isArray(stream.entries)) ? stream.entries : [];
-                    for (const ent of entries) {
-                        const msg = ent && (ent.message || ent.msg || ent) ? (ent.message || ent.msg || ent) : '';
-                        if (q && String(msg).includes(q)) {
-                            const now2 = Date.now();
-                            return { success: true, condition: 'present', query: q, poll_count: pollCount, duration_ms: now2 - start, stable_duration_ms: 0, matchedLog: { message: msg, raw: ent }, matchSource: 'log-stream', timestamp: now2, type: 'log', observed_state: true };
-                        }
-                    }
-                    const gl = await ToolsObserve.getLogsHandler({ platform, deviceId, lines: 200 });
-                    const logsArr = Array.isArray(gl && gl.logs) ? gl.logs : [];
-                    // Normalize to messages for comparison
-                    const msgs = ToolsInteract._logsToMessages(logsArr);
-                    let startIndex = 0;
-                    if (baselineLastLine) {
-                        const idx = msgs.lastIndexOf(baselineLastLine);
-                        startIndex = idx >= 0 ? idx + 1 : 0;
-                    }
-                    for (let i = startIndex; i < msgs.length; i++) {
-                        const line = msgs[i];
-                        if (q && String(line).includes(q)) {
-                            const now2 = Date.now();
-                            return { success: true, condition: 'present', query: q, poll_count: pollCount, duration_ms: now2 - start, stable_duration_ms: 0, matchedLog: { message: line }, matchSource: 'log-snapshot', timestamp: now2, type: 'log', observed_state: true };
-                        }
-                    }
-                }
-                catch (err) {
-                    checkDebuggerGuard();
-                    console.error('waitForUI(log) error:', err);
-                }
-            }
-            else if (type === 'screen') {
-                try {
-                    const fpRes = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId });
-                    const fp = fpRes?.fingerprint ?? null;
-                    if (fp !== null && fp !== undefined && fp !== initialFingerprint) {
-                        // when screen changed, require stability_ms where fingerprint remains the same
-                        if (matchedAt === null)
-                            matchedAt = now;
-                        const confirmFp = (await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId }))?.fingerprint ?? null;
-                        if (confirmFp === fp) {
-                            stableDuration = Date.now() - matchedAt;
-                            lastObservedState = true;
-                            if (stableDuration >= stability_ms) {
-                                const now2 = Date.now();
-                                return { success: true, condition: 'present', query: q, poll_count: pollCount, duration_ms: now2 - start, stable_duration_ms: stableDuration, newFingerprint: fp, matchSource: 'screen-fingerprint', timestamp: now2, type: 'screen', observed_state: lastObservedState ?? null };
-                            }
-                        }
-                        else {
-                            matchedAt = null;
-                            stableDuration = 0;
-                            lastObservedState = false;
-                        }
-                    }
-                }
-                catch (err) {
-                    checkDebuggerGuard();
-                    console.error('waitForUI(screen) error:', err);
-                }
-            }
-            else if (type === 'idle') {
-                try {
-                    const fpRes = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId });
-                    const fp = fpRes?.fingerprint ?? null;
-                    if (fp !== prevFingerprint) {
-                        prevFingerprint = fp;
-                        lastChangeAt = Date.now();
-                        matchedAt = null;
-                        stableDuration = 0;
-                        lastObservedState = false;
-                    }
-                    else {
-                        const idleMs = Date.now() - lastChangeAt;
-                        lastObservedState = true;
-                        if (idleMs >= stability_ms) {
-                            const now2 = Date.now();
-                            return { success: true, condition: 'present', query: q, poll_count: pollCount, duration_ms: now2 - start, stable_duration_ms: idleMs, matchSource: 'idle-stable', timestamp: now2, type: 'idle', observed_state: lastObservedState ?? null };
-                        }
-                    }
-                }
-                catch (err) {
-                    checkDebuggerGuard();
-                    console.error('waitForUI(idle) error:', err);
-                }
-            }
-            // Respect poll interval and avoid tight loop
-            await sleep(pollInterval);
-        }
-        // On timeout, optionally capture a failure snapshot to aid debugging (best-effort)
-        let snapshot = null;
-        if (includeSnapshotOnFailure) {
-            try {
-                // Use dynamic import to avoid circular-initialization issues where the ToolsObserve
-                // binding captured earlier may not reflect test-time overrides. Importing at call
-                // time ensures the latest exported ToolsObserve object is used.
-                const Obs = await import('../observe/index.js');
-                snapshot = await Obs.ToolsObserve.captureDebugSnapshotHandler({ reason: `wait_for_ui timeout for ${type}`, includeLogs: true, platform, deviceId });
-            }
-            catch (err) {
-                checkDebuggerGuard();
-                snapshot = { error: err instanceof Error ? err.message : String(err) };
-            }
-        }
-        const elapsed = Date.now() - start;
-        return { success: false, condition: match, query: q, poll_count: pollCount, duration_ms: elapsed, stable_duration_ms: stableDuration, error: 'Timeout waiting for condition', snapshot, observed_state: lastObservedState ?? null };
+    static async waitForUICore(input) {
+        return waitForUICore(input, { fingerprint: target => ToolsObserve.getScreenFingerprintHandler(target), logs: target => ToolsObserve.getLogsHandler(target),
+            stream: target => ToolsObserve.readLogStreamHandler(target), find: input => ToolsInteract.findElementHandler(input),
+            snapshot: async (input) => { const { ToolsObserve } = await import('../observe/index.js'); return ToolsObserve.captureDebugSnapshotHandler(input); } });
     }
 }