mobile-debug-mcp 0.33.0 → 0.35.0

package/dist/interact/assertions/state-assertion-context.js

@@ -0,0 +1,35 @@
+import { systemClock } from '../../runtime/clock.js';
+import { createTraceStep, nextActionId } from '../../runtime/action-results.js';
+export function createStateAssertion({ 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 }, clock = systemClock) {
+    const start = clock.now();
+    return { clock, input: { selector, element_id, property, expected, platform, deviceId }, start,
+        deadline: start + (exact_budget ? stabilization_window_ms : Math.max(500, stabilization_window_ms)),
+        stableTarget: Math.max(1, Math.floor(stable_observation_count || 2)),
+        delay: exact_budget ? Math.max(50, Math.min(poll_interval_ms || 150, 1000)) : Math.max(100, Math.min(poll_interval_ms || 150, 200)),
+        stale: Math.max(300, Math.min(snapshot_stale_threshold_ms || 500, 800)), attempts: 0, stable: 0, reason: 'element not found',
+        failure: 'ELEMENT_NOT_FOUND', element: null,
+        value: null, raw: null, id: element_id ?? null,
+        trace: [], sequence: 0, resolveRecorded: false };
+}
+export function recordState(s, stage, result, metadata) {
+    s.trace.push(createTraceStep({ stage, timestamp: s.clock.now(), result, attemptIndex: s.sequence++, metadata }));
+}
+export function stabilizeState(s, result, age, reason) {
+    recordState(s, 'stabilize', result, { stabilization_attempts: s.attempts, stable_observation_count: s.stable, snapshot_freshness_ms: age, reason });
+}
+function trace(s, outcome) {
+    return { action_id: nextActionId('expect_state', s.clock.now()), steps: s.trace, final_outcome: outcome, attempts: s.attempts };
+}
+export function stateSuccess(s, comparison, age) {
+    return { success: true, selector: s.input.selector, element_id: s.id,
+        expected_state: { property: s.input.property, expected: s.input.expected }, element: s.element,
+        observed_state: { property: s.input.property, value: comparison.observedValue, ...(comparison.rawValue !== null ? { raw_value: comparison.rawValue } : {}) },
+        reason: comparison.reason, stabilization_attempts: s.attempts, stabilization_window_ms: s.clock.now() - s.start,
+        stable_observation_count: s.stable, snapshot_freshness_ms: age ?? undefined, trace: trace(s, 'success') };
+}
+export function stateFailure(s) {
+    return { success: false, selector: s.input.selector, element_id: s.id,
+        expected_state: { property: s.input.property, expected: s.input.expected }, element: s.element,
+        observed_state: { property: s.input.property, value: s.value, ...(s.raw !== null ? { raw_value: s.raw } : {}) },
+        reason: s.reason, failure_code: s.failure, retryable: true, trace: trace(s, 'failure') };
+}

package/dist/interact/assertions/state-assertion.js

@@ -0,0 +1,76 @@
+import { _findFirstMatchingElement } from '../targeting/element-helpers.js';
+import { compareReadableState } from './state-comparison.js';
+import { createStateAssertion, recordState, stabilizeState, stateSuccess, stateFailure } from './state-assertion-context.js';
+function matchState(s, tree, deps) {
+    const elements = Array.isArray(tree?.elements) ? tree.elements : [];
+    const platform = tree?.device?.platform === 'ios' ? 'ios' : s.input.platform || 'android';
+    const deviceId = tree?.device?.id || s.input.deviceId;
+    const age = typeof tree?.captured_at_ms === 'number' ? s.clock.now() - tree.captured_at_ms : null;
+    let matched = null;
+    if (s.input.element_id) {
+        const handle = deps.getHandle(s.input.element_id);
+        if (handle) {
+            const current = deps.currentHandle(elements, platform, deviceId, handle);
+            if (current)
+                matched = { el: current.el, idx: current.index };
+        }
+    }
+    if (!matched && s.input.selector)
+        matched = _findFirstMatchingElement(elements, s.input.selector);
+    return { matched, platform, deviceId, age };
+}
+function retryResolution(s, matched, age) {
+    s.reason = matched ? 'stale snapshot' : 'element not found';
+    s.failure = matched ? 'UNKNOWN' : 'ELEMENT_NOT_FOUND';
+    s.stable = 0;
+    recordState(s, 'resolve', 'retry', { selector: s.input.selector ?? null, element_id: s.id, matched, reason: s.reason, attempt: s.attempts });
+    stabilizeState(s, 'retry', age, s.reason);
+}
+async function sample(s, deps) {
+    s.attempts++;
+    const tree = await deps.observe({ platform: s.input.platform, deviceId: s.input.deviceId });
+    const { matched, platform, deviceId, age } = matchState(s, tree, deps);
+    if (!matched) {
+        retryResolution(s, false, age);
+        return null;
+    }
+    const element = deps.target(platform, deviceId, matched);
+    s.id = element.elementId;
+    s.element = { ...element, state: matched.el.state ?? null };
+    if (age !== null && age > s.stale) {
+        retryResolution(s, true, age);
+        return null;
+    }
+    if (!s.resolveRecorded) {
+        recordState(s, 'resolve', 'success', { selector: s.input.selector ?? null, element_id: s.id, matched: true, reason: 'element resolved' });
+        s.resolveRecorded = true;
+    }
+    const comparison = compareReadableState(s.input.property, s.input.expected, matched.el.state ?? null);
+    if (comparison.success) {
+        s.stable++;
+        stabilizeState(s, 'success', age, comparison.reason);
+        recordState(s, 'verify', 'success', { property: s.input.property, expected: s.input.expected, observed_value: comparison.observedValue, reason: comparison.reason });
+        if (s.stable >= s.stableTarget)
+            return stateSuccess(s, comparison, age);
+    }
+    else {
+        s.stable = 0;
+        s.reason = comparison.reason || s.reason;
+        s.failure = 'UNKNOWN';
+        stabilizeState(s, 'retry', age, s.reason);
+        recordState(s, 'verify', 'retry', { property: s.input.property, expected: s.input.expected, observed_value: comparison.observedValue, reason: s.reason });
+        s.value = comparison.observedValue;
+        s.raw = comparison.rawValue;
+    }
+    return null;
+}
+export async function expectState(input, deps) {
+    const state = createStateAssertion(input, deps.clock);
+    while (state.clock.now() <= state.deadline) {
+        const result = await sample(state, deps);
+        if (result)
+            return result;
+        await state.clock.sleep(state.delay);
+    }
+    return stateFailure(state);
+}

package/dist/interact/assertions/state-comparison.js

@@ -0,0 +1,141 @@
+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;
+export function compareReadableState(property, expected, observedState) {
+    const input = { property, expected, observedState, actual: observedState?.[property] ?? null };
+    if (['checked', 'focused', 'expanded', 'enabled'].includes(property))
+        return compareBooleanState(input);
+    if (['value', 'raw_value'].includes(property))
+        return compareValueState(input);
+    if (property === 'selected')
+        return compareSelectedState(input);
+    if (property === 'text_value')
+        return compareTextState(input);
+    return compareOtherState(input);
+}
+function compareBooleanState({ property, expected, actual }) {
+    let success = false;
+    let reason = '';
+    let rawValue = null;
+    let observedValue = actual;
+    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;
+    return { success, reason, rawValue, observedValue };
+}
+function compareValueState({ expected, actual }) {
+    let success = false;
+    let reason = '';
+    let rawValue = null;
+    let observedValue = actual;
+    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}`;
+        return { success, reason, rawValue, observedValue };
+    }
+    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';
+    }
+    return { success, reason, rawValue, observedValue };
+}
+function compareSelectedState({ expected, actual, observedState }) {
+    let success = false;
+    let reason = '';
+    let rawValue = null;
+    let observedValue = actual;
+    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';
+        return { success, reason, rawValue, observedValue };
+    }
+    if (expectedBool !== null) {
+        const actualBool = typeof observedState.selected === 'boolean' ? observedState.selected : null;
+        if (actualBool === null) {
+            reason = 'selected state is not boolean';
+            return { success, reason, rawValue, observedValue };
+        }
+        rawValue = actualBool;
+        observedValue = actualBool;
+        success = actualBool === expectedBool;
+        reason = success ? 'selected matches expected value' : `expected selected=${expectedBool} but observed ${actualBool}`;
+        return { success, reason, rawValue, observedValue };
+    }
+    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';
+        return { success, reason, rawValue, observedValue };
+    }
+    rawValue = actualString;
+    observedValue = actualString;
+    success = actualString === expectedString;
+    reason = success ? 'selected matches expected value' : `expected selected=${expectedString} but observed ${actualString}`;
+    return { success, reason, rawValue, observedValue };
+}
+function compareTextState({ expected, actual }) {
+    let success = false;
+    let reason = '';
+    let rawValue = null;
+    let observedValue = actual;
+    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}`;
+    }
+    return { success, reason, rawValue, observedValue };
+}
+function compareOtherState({ property, expected, actual }) {
+    let success = false;
+    let reason = '';
+    let rawValue = null;
+    let observedValue = actual;
+    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}`;
+    }
+    return { success, reason, rawValue, observedValue };
+}

package/dist/interact/assertions/visibility-assertion.js

@@ -0,0 +1,34 @@
+import { buildObservationTrace } from '../interaction-trace.js';
+function visibleElement(element) {
+    return { elementId: element.elementId ?? null, text: element.text ?? null, resource_id: element.resource_id ?? null,
+        accessibility_id: element.accessibility_id ?? null, class: element.class ?? null, bounds: element.bounds ?? null,
+        index: typeof element.index === 'number' ? element.index : null, 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 };
+}
+function visibleSuccess(input, result, element) {
+    const id = element.elementId ?? input.element_id ?? null;
+    return { success: true, selector: input.selector, element_id: id, expected_condition: 'visible', element: visibleElement(element),
+        observed: { status: result.status, matched_count: typeof result.matched === 'number' ? result.matched : result.observed?.matched_count ?? null,
+            condition_satisfied: true, selected_index: typeof element.index === 'number' ? element.index : null, last_matched_element: visibleElement(element) },
+        reason: 'selector is visible', trace: buildObservationTrace({ actionType: 'expect_element_visible', stage: 'verify', success: true, attempts: 1,
+            metadata: { selector: input.selector, element_id: id, status: result.status } }) };
+}
+function visibleFailure(input, result) {
+    const code = result?.error?.code === 'INTERNAL_ERROR' ? 'UNKNOWN' : 'TIMEOUT';
+    const reason = result?.error?.message ?? 'selector is not visible';
+    return { success: false, selector: input.selector, element_id: input.element_id ?? null, expected_condition: 'visible',
+        observed: failureObserved(result), reason, failure_code: code, retryable: code === 'TIMEOUT',
+        trace: buildObservationTrace({ actionType: 'expect_element_visible', stage: 'verify', success: false, attempts: 1,
+            metadata: { selector: input.selector, element_id: input.element_id ?? null, status: result?.status ?? null, reason } }) };
+}
+export async function expectVisible({ selector, element_id, timeout_ms = 5000, poll_interval_ms = 300, platform, deviceId }, wait) {
+    const result = await wait({ selector, condition: 'visible', timeout_ms, poll_interval_ms, platform, deviceId });
+    const input = { selector, element_id, platform, deviceId };
+    return result?.status === 'success' && result.element ? visibleSuccess(input, result, result.element) : visibleFailure(input, result);
+}
+function failureObserved(result) {
+    return { 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 };
+}

package/dist/interact/conditional-action.js

@@ -2,14 +2,16 @@ import { AsyncLocalStorage } from 'node:async_hooks';
 import { ToolsObserve } from '../observe/index.js';
 import { getSnapshotSessionId, hasSnapshotBaseline } from '../observe/snapshot-metadata.js';
 import { runWithSeparateBudget } from '../utils/operation-budget.js';
-import { ToolsNetwork } from '../network/index.js';
+import { ToolsNetwork } from '../observe/network/index.js';
 const context = new AsyncLocalStorage();
 export function createConditionalAction(platform, deviceId, expected) {
-    return { platform, deviceId, expected, result: {
+    return {
+        platform, deviceId, expected, result: {
             status: 'not_checked',
             expected: { snapshot_session_id: expected.snapshotSessionId, snapshot_revision: expected.snapshotRevision },
             observed: null, elapsed_ms: 0, reason: 'ACTION_NOT_REACHED'
-        } };
+        }
+    };
 }
 export function withConditionalAction(condition, operation) {
     return context.run(condition, operation);
@@ -45,10 +47,7 @@ export async function beforeInputDispatch(platform, deviceId) {
             const tree = await runWithSeparateBudget(condition.expected.timeoutMs ?? 15000, () => ToolsObserve.getUITreeHandler({ platform, deviceId }));
             if (tree?.error)
                 result.reason = 'OBSERVATION_FAILED';
-            else if (!tree || !Array.isArray(tree.elements) || !Number.isSafeInteger(tree.snapshot_revision) || tree.snapshot_revision < 1 ||
-                tree.snapshot_session_id !== getSnapshotSessionId() || !Number.isFinite(tree.captured_at_ms) || tree.captured_at_ms <= 0 ||
-                !tree.resolution || !Number.isFinite(tree.resolution.width) || !Number.isFinite(tree.resolution.height) ||
-                !(tree.resolution.width > 0) || !(tree.resolution.height > 0))
+            else if (invalidConditionSnapshot(tree))
                 result.reason = 'OBSERVATION_INVALID';
             else if (tree.device?.platform !== platform || tree.device?.id !== deviceId)
                 result.reason = 'DEVICE_MISMATCH';
@@ -66,3 +65,9 @@ export async function beforeInputDispatch(platform, deviceId) {
         throw new Error(conditionFailureCode(condition));
     ToolsNetwork.notifyActionStart();
 }
+function invalidConditionSnapshot(tree) {
+    return !tree || !Array.isArray(tree.elements) || !Number.isSafeInteger(tree.snapshot_revision) || tree.snapshot_revision < 1 ||
+        tree.snapshot_session_id !== getSnapshotSessionId() || !Number.isFinite(tree.captured_at_ms) || tree.captured_at_ms <= 0 ||
+        !tree.resolution || !Number.isFinite(tree.resolution.width) || !Number.isFinite(tree.resolution.height) ||
+        !(tree.resolution.width > 0) || !(tree.resolution.height > 0);
+}