mobile-debug-mcp 0.26.4 → 0.27.0

package/dist/interact/index.js

@@ -226,6 +226,13 @@ export class ToolsInteract {
         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;
@@ -284,6 +291,38 @@ export class ToolsInteract {
         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 ?? '');
@@ -318,11 +357,11 @@ export class ToolsInteract {
     static _resolveActionableAncestor(elements, chosen) {
         if (!chosen)
             return null;
-        if (chosen.el.clickable || chosen.el.focusable)
+        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) && current.el.parentId !== undefined && current.el.parentId !== null) {
+        while (safety < 20 && current.el && !(current.el.clickable || current.el.focusable || ToolsInteract._isSemanticActionable(current.el)) && current.el.parentId !== undefined && current.el.parentId !== null) {
             const parentId = current.el.parentId;
             let parentIndex = null;
             if (typeof parentId === 'number')
@@ -331,7 +370,7 @@ export class ToolsInteract {
                 parentIndex = Number(parentId);
             if (parentIndex !== null && elements[parentIndex]) {
                 current = { el: elements[parentIndex], idx: parentIndex };
-                if (current.el.clickable || current.el.focusable)
+                if (current.el.clickable || current.el.focusable || ToolsInteract._isSemanticActionable(current.el))
                     return current;
             }
             else if (typeof parentId === 'string') {
@@ -339,7 +378,7 @@ export class ToolsInteract {
                 if (foundIndex === -1)
                     break;
                 current = { el: elements[foundIndex], idx: foundIndex };
-                if (current.el.clickable || current.el.focusable)
+                if (current.el.clickable || current.el.focusable || ToolsInteract._isSemanticActionable(current.el))
                     return current;
             }
             else {
@@ -355,7 +394,7 @@ export class ToolsInteract {
         let bestArea = Infinity;
         for (let i = 0; i < elements.length; i++) {
             const el = elements[i];
-            if (!el || !(el.clickable || el.focusable))
+            if (!el || !(el.clickable || el.focusable || ToolsInteract._isSemanticActionable(el)))
                 continue;
             const bounds = ToolsInteract._normalizeBounds(el.bounds);
             if (!bounds)
@@ -736,6 +775,7 @@ export class ToolsInteract {
             const currentPoint = currentValue !== null
                 ? ToolsInteract._buildControlPoint(bounds, (currentValue - min) / (max - min), axis)
                 : ToolsInteract._buildControlPoint(bounds, 0.5, axis);
+            const probePoints = ToolsInteract._buildAdjustmentProbePoints(bounds, targetValue, currentValue, min, max, axis);
             const runVerification = async () => {
                 const verification = await ToolsInteract.expectStateHandler({
                     element_id: resolvedTarget?.elementId ?? element_id,
@@ -763,36 +803,66 @@ export class ToolsInteract {
                     withinTolerance: observedValue !== null && Math.abs(observedValue - targetValue) <= normalizedTolerance
                 };
             };
-            lastAdjustmentMode = 'coordinate';
-            const primaryActionResult = await ToolsInteract.tapHandler({
-                platform: resolvedPlatform,
-                x: targetPoint.x,
-                y: targetPoint.y,
-                deviceId: resolvedDeviceId
-            });
-            let actionDevice = primaryActionResult.device ?? currentDevice;
-            attemptCount++;
-            if (!primaryActionResult.success) {
-                lastAdjustmentMode = 'gesture';
-                const fallbackActionResult = await ToolsInteract.swipeHandler({
+            let actionDevice = currentDevice;
+            let observedState = actualState;
+            let verification = null;
+            let verificationResult = { verification: null, observedState: actualState, withinTolerance: false };
+            for (let i = 0; i < probePoints.length; i++) {
+                const probePoint = probePoints[i];
+                lastAdjustmentMode = 'coordinate';
+                const actionResult = await ToolsInteract.tapHandler({
                     platform: resolvedPlatform,
-                    x1: currentPoint.x,
-                    y1: currentPoint.y,
-                    x2: targetPoint.x,
-                    y2: targetPoint.y,
-                    duration: 220,
+                    x: probePoint.x,
+                    y: probePoint.y,
                     deviceId: resolvedDeviceId
                 });
                 attemptCount++;
-                if (!fallbackActionResult.success) {
-                    return buildFailure('UNKNOWN', fallbackActionResult.error ?? primaryActionResult.error ?? 'adjustment gesture failed', resolvedTarget, fallbackActionResult.device ?? primaryActionResult.device, actualState, attemptCount, lastAdjustmentMode, false);
+                actionDevice = actionResult.device ?? actionDevice;
+                if (!actionResult.success) {
+                    continue;
+                }
+                verificationResult = await runVerification();
+                observedState = verificationResult.observedState;
+                lastObservedState = observedState;
+                if (verificationResult.withinTolerance) {
+                    const uiFingerprintAfter = await ToolsInteract._captureFingerprint(resolvedPlatform, resolvedDeviceId);
+                    const base = buildActionExecutionResult({
+                        actionType,
+                        sourceModule: 'interact',
+                        device: actionDevice ?? currentDevice,
+                        selector: targetSelector,
+                        resolved: resolvedTarget,
+                        success: true,
+                        uiFingerprintBefore: fingerprintBefore,
+                        uiFingerprintAfter,
+                        details: {
+                            target_value: targetValue,
+                            tolerance: normalizedTolerance,
+                            property,
+                            attempts: attemptCount,
+                            adjustment_mode: lastAdjustmentMode,
+                            actual_state: observedState,
+                            converged: true,
+                            within_tolerance: true,
+                            reason: verificationResult.verification?.reason ?? 'control converged to target value'
+                        }
+                    });
+                    return {
+                        ...base,
+                        target_state: {
+                            property,
+                            target_value: targetValue,
+                            tolerance: normalizedTolerance
+                        },
+                        actual_state: observedState,
+                        within_tolerance: true,
+                        converged: true,
+                        attempts: attemptCount,
+                        adjustment_mode: lastAdjustmentMode
+                    };
                 }
-                actionDevice = fallbackActionResult.device ?? actionDevice;
             }
-            let verificationResult = await runVerification();
-            let observedState = verificationResult.observedState;
-            lastObservedState = observedState;
-            if (!verificationResult.withinTolerance && currentValue !== null) {
+            if (currentValue !== null) {
                 lastAdjustmentMode = 'gesture';
                 const fallbackActionResult = await ToolsInteract.swipeHandler({
                     platform: resolvedPlatform,
@@ -805,12 +875,51 @@ export class ToolsInteract {
                 });
                 attemptCount++;
                 if (!fallbackActionResult.success) {
-                    return buildFailure('UNKNOWN', fallbackActionResult.error ?? 'adjustment gesture failed', resolvedTarget, fallbackActionResult.device, observedState ?? actualState, attemptCount, lastAdjustmentMode, 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;
+                if (verificationResult.withinTolerance) {
+                    const uiFingerprintAfter = await ToolsInteract._captureFingerprint(resolvedPlatform, resolvedDeviceId);
+                    const base = buildActionExecutionResult({
+                        actionType,
+                        sourceModule: 'interact',
+                        device: actionDevice ?? currentDevice,
+                        selector: targetSelector,
+                        resolved: resolvedTarget,
+                        success: true,
+                        uiFingerprintBefore: fingerprintBefore,
+                        uiFingerprintAfter,
+                        details: {
+                            target_value: targetValue,
+                            tolerance: normalizedTolerance,
+                            property,
+                            attempts: attemptCount,
+                            adjustment_mode: lastAdjustmentMode,
+                            actual_state: observedState,
+                            converged: true,
+                            within_tolerance: true,
+                            reason: verificationResult.verification?.reason ?? 'control converged to target value'
+                        }
+                    });
+                    return {
+                        ...base,
+                        target_state: {
+                            property,
+                            target_value: targetValue,
+                            tolerance: normalizedTolerance
+                        },
+                        actual_state: observedState,
+                        within_tolerance: true,
+                        converged: true,
+                        attempts: attemptCount,
+                        adjustment_mode: lastAdjustmentMode
+                    };
+                }
             }
-            const verification = verificationResult.verification;
+            verification = verificationResult.verification;
             lastObservedState = observedState;
             if (verificationResult.withinTolerance) {
                 const uiFingerprintAfter = await ToolsInteract._captureFingerprint(resolvedPlatform, resolvedDeviceId);
@@ -904,11 +1013,13 @@ export class ToolsInteract {
             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);
+            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) {
@@ -959,6 +1070,30 @@ export class ToolsInteract {
                     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)
@@ -1087,7 +1222,7 @@ export class ToolsInteract {
                     interactable: true
                 };
             }
-            if (best && !(best.el.clickable || best.el.focusable)) {
+            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 = {
@@ -1191,6 +1326,10 @@ export class ToolsInteract {
         let lastMatchedCount = 0;
         let lastMatchedElement = null;
         let lastConditionSatisfied = false;
+        let matchedAt = null;
+        let stableMatchCount = 0;
+        const stableObservationCount = 2;
+        const snapshotStaleThresholdMs = 500;
         // Precompute normalized selector values and helpers (constant across polls)
         const normalize = ToolsInteract._normalize;
         const containsFlag = !!selector?.contains;
@@ -1305,23 +1444,34 @@ export class ToolsInteract {
                         lastMatchedCount = matchedCount;
                         lastConditionSatisfied = conditionMet;
                         lastMatchedElement = matchedElement ? ToolsInteract._buildResolvedElement(resolvedPlatform, resolvedDeviceId, matchedElement.el, matchedElement.idx) : null;
-                        if (conditionMet) {
-                            const now = Date.now();
-                            const latency_ms = now - overallStart;
-                            const outEl = lastMatchedElement;
-                            return {
-                                status: 'success',
-                                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
-                                }
-                            };
+                        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) {
+                                const latency_ms = now - overallStart;
+                                const outEl = lastMatchedElement;
+                                return {
+                                    status: 'success',
+                                    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) {
@@ -1641,174 +1791,224 @@ export class ToolsInteract {
             retryable: errorCode === 'TIMEOUT'
         };
     }
-    static async expectStateHandler({ selector, element_id, property, expected, platform, deviceId }) {
-        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;
-        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) {
-            return {
-                success: false,
-                selector,
-                element_id: element_id ?? null,
-                expected_state: { property, expected },
-                reason: 'element not found',
-                failure_code: 'ELEMENT_NOT_FOUND',
-                retryable: true
-            };
-        }
-        const resolvedElement = ToolsInteract._resolvedTargetFromElement(ToolsInteract._computeElementId(treePlatform, treeDeviceId, matched.el, matched.idx), matched.el, matched.idx);
-        const observedState = matched.el.state ?? null;
-        const actual = observedState?.[property] ?? null;
+    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 }) {
         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;
-        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}`;
+        const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+        const start = Date.now();
+        const deadline = start + Math.max(500, stabilization_window_ms);
+        const stableTarget = Math.max(1, Math.floor(stable_observation_count || 2));
+        const pollDelay = 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;
+        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 };
                 }
-                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;
+            if (!matched && selector) {
+                matched = ToolsInteract._findFirstMatchingElement(elements, selector);
             }
-            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';
+            if (!matched) {
+                lastReason = 'element not found';
+                lastFailureCode = 'ELEMENT_NOT_FOUND';
+                stableCount = 0;
+                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;
+                await sleep(pollDelay);
+                continue;
+            }
+            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;
                 }
-                if (expectedBool !== null) {
-                    const actualBool = typeof observedState.selected === 'boolean' ? observedState.selected : null;
-                    if (actualBool === null) {
-                        reason = 'selected state is not boolean';
+                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;
                     }
-                    rawValue = actualBool;
-                    observedValue = actualBool;
-                    success = actualBool === expectedBool;
-                    reason = success ? 'selected matches expected value' : `expected selected=${expectedBool} but observed ${actualBool}`;
+                    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;
                 }
-                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';
+                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;
                 }
-                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';
+                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;
                 }
-                else {
-                    success = actualString === expectedString;
-                    rawValue = actualString;
-                    observedValue = actualString;
-                    reason = success ? 'text_value matches expected value' : `expected text_value=${expectedString} but observed ${actualString}`;
+                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}`;
+                    }
                 }
-                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++;
+                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
+                    };
                 }
             }
-        }
-        if (!success && !reason) {
-            reason = `${property} did not match expected value`;
+            else {
+                stableCount = 0;
+                lastReason = reason || lastReason;
+                lastFailureCode = 'UNKNOWN';
+            }
+            if (!success) {
+                lastObservedValue = observedValue;
+                lastRawValue = rawValue;
+            }
+            await sleep(pollDelay);
         }
         return {
-            success,
+            success: false,
             selector,
-            element_id: element_id ?? resolvedElement.elementId,
+            element_id: lastResolvedElementId,
             expected_state: { property, expected },
-            element: {
-                ...resolvedElement,
-                state: observedState
-            },
+            element: lastObservedElement,
             observed_state: {
                 property,
-                value: observedValue,
-                ...(rawValue !== null ? { raw_value: rawValue } : {})
+                value: lastObservedValue,
+                ...(lastRawValue !== null ? { raw_value: lastRawValue } : {})
             },
-            reason,
-            ...(success ? {} : { failure_code: 'UNKNOWN', retryable: false })
+            reason: lastReason,
+            failure_code: lastFailureCode,
+            retryable: true
         };
     }
     static async waitForUICore({ type = 'ui', query, timeoutMs = 30000, pollIntervalMs = 300, includeSnapshotOnFailure = true, match = 'present', stability_ms = 700, observationDelayMs = 0, platform, deviceId }) {