mobile-debug-mcp 0.34.0 → 0.36.0

package/dist/interact/waits/legacy-log-wait.js

@@ -0,0 +1,38 @@
+import { checkDebuggerGuard } from '../../debugger/guard.js';
+import { logMessages, legacySuccess } from './legacy-wait-state.js';
+function streamMessage(entry) {
+    if (!entry)
+        return '';
+    if (typeof entry === 'object') {
+        const fields = entry;
+        return fields.message || fields.msg || entry;
+    }
+    return entry;
+}
+export async function legacyLog(s, deps) {
+    try {
+        const stream = await deps.stream({ platform: s.target.platform, sessionId: 'default', limit: 200 });
+        for (const entry of stream && Array.isArray(stream.entries) ? stream.entries : []) {
+            const message = streamMessage(entry);
+            if (s.query && String(message).includes(s.query)) {
+                const result = legacySuccess(s, 'log', 'log-stream', 0, { matchedLog: { message, raw: entry } });
+                return { ...result, observed_state: true };
+            }
+        }
+        const logs = await deps.logs({ ...s.target, lines: 200 });
+        const messages = logMessages(Array.isArray(logs && logs.logs) ? logs.logs : []);
+        const index = s.baseline ? messages.lastIndexOf(s.baseline) : -1;
+        for (let i = index >= 0 ? index + 1 : 0; i < messages.length; i++) {
+            const message = messages[i];
+            if (s.query && String(message).includes(s.query)) {
+                const result = legacySuccess(s, 'log', 'log-snapshot', 0, { matchedLog: { message } });
+                return { ...result, observed_state: true };
+            }
+        }
+    }
+    catch (error) {
+        checkDebuggerGuard();
+        console.error('waitForUI(log) error:', error);
+    }
+    return null;
+}

package/dist/interact/waits/legacy-wait-observations.js

@@ -0,0 +1,103 @@
+import { checkDebuggerGuard } from '../../debugger/guard.js';
+import { logMessages, legacySuccess } from './legacy-wait-state.js';
+async function withTimeout(promise, ms, clock) {
+    return Promise.race([promise, clock.sleep(ms).then(() => null)]);
+}
+export async function legacyBaseline(s, deps) {
+    try {
+        const fingerprint = deps.fingerprint(s.target), logs = deps.logs({ ...s.target, lines: 200 });
+        const [fp, result] = await Promise.all([withTimeout(fingerprint, 300, s.clock), withTimeout(logs, 500, s.clock)]);
+        if (fp && typeof fp === 'object')
+            s.initial = fp.fingerprint ?? null;
+        if (result) {
+            const messages = logMessages(Array.isArray(result.logs) ? result.logs : []);
+            s.baseline = messages.length ? messages[messages.length - 1] : null;
+        }
+    }
+    catch (error) {
+        checkDebuggerGuard();
+        try {
+            console.warn('waitForUI: failed to get baseline data (non-fatal):', error instanceof Error ? error.message : String(error));
+        }
+        catch { /* Logging is best-effort. */ }
+    }
+}
+export async function legacyUI(s, deps) {
+    try {
+        try {
+            const found = await deps.find({ query: s.query, exact: false, timeoutMs: Math.min(500, s.interval), ...s.target });
+            const present = !!(found && found.found), matched = s.match === 'present' ? present : !present;
+            if (matched) {
+                if (s.matched === null)
+                    s.matched = s.clock.now();
+                s.duration = s.clock.now() - s.matched;
+                s.observed = true;
+                if (s.duration >= s.stability_ms)
+                    return legacySuccess(s, 'ui', 'ui-find', s.duration, { matchedElement: present ? found.element : null }, s.match);
+            }
+            else {
+                s.matched = null;
+                s.duration = 0;
+                s.observed = false;
+            }
+        }
+        catch (error) {
+            checkDebuggerGuard();
+            console.error('waitForUI(ui) find error:', error);
+        }
+    }
+    catch (error) {
+        checkDebuggerGuard();
+        console.error('waitForUI(ui) outer error:', error);
+    }
+    return null;
+}
+export async function legacyScreen(s, deps, now) {
+    try {
+        const fp = (await deps.fingerprint(s.target))?.fingerprint ?? null;
+        if (fp !== null && fp !== undefined && fp !== s.initial) {
+            if (s.matched === null)
+                s.matched = now;
+            const confirm = (await deps.fingerprint(s.target))?.fingerprint ?? null;
+            if (confirm === fp) {
+                s.duration = s.clock.now() - s.matched;
+                s.observed = true;
+                if (s.duration >= s.stability_ms)
+                    return legacySuccess(s, 'screen', 'screen-fingerprint', s.duration, { newFingerprint: fp });
+            }
+            else {
+                s.matched = null;
+                s.duration = 0;
+                s.observed = false;
+            }
+        }
+    }
+    catch (error) {
+        checkDebuggerGuard();
+        console.error('waitForUI(screen) error:', error);
+    }
+    return null;
+}
+export async function legacyIdle(s, deps) {
+    try {
+        const fp = (await deps.fingerprint(s.target))?.fingerprint ?? null;
+        if (fp !== s.previous) {
+            s.previous = fp;
+            s.lastChange = s.clock.now();
+            s.matched = null;
+            s.duration = 0;
+            s.observed = false;
+        }
+        else {
+            const idle = s.clock.now() - s.lastChange;
+            s.observed = true;
+            if (idle >= s.stability_ms)
+                return legacySuccess(s, 'idle', 'idle-stable', idle);
+        }
+    }
+    catch (error) {
+        checkDebuggerGuard();
+        console.error('waitForUI(idle) error:', error);
+    }
+    return null;
+}

package/dist/interact/waits/legacy-wait-state.js

@@ -0,0 +1,34 @@
+import { systemClock } from '../../runtime/clock.js';
+export function createLegacyWait({ type = 'ui', query, timeoutMs = 30000, pollIntervalMs = 300, includeSnapshotOnFailure = true, match = 'present', stability_ms = 700, observationDelayMs = 0, platform, deviceId }, clock = systemClock) {
+    const start = clock.now();
+    return { clock, type, query: query == null ? '' : String(query), start, deadline: start + (timeoutMs || 0),
+        interval: Math.max(250, Math.min(pollIntervalMs || 300, 500)), includeSnapshotOnFailure, match, stability_ms, observationDelayMs,
+        target: { platform, deviceId }, initial: null, baseline: null,
+        lastChange: 0, previous: null, polls: 0, matched: null,
+        observed: null, duration: 0 };
+}
+export function logMessages(entries) {
+    if (!Array.isArray(entries))
+        return [];
+    return entries.map(entry => {
+        if (typeof entry === 'string')
+            return entry;
+        if (entry && typeof entry === 'object') {
+            const fields = entry;
+            if (fields.message || fields.msg)
+                return fields.message || fields.msg;
+        }
+        try {
+            return JSON.stringify(entry);
+        }
+        catch {
+            return String(entry);
+        }
+    });
+}
+export function legacySuccess(s, type, matchSource, stable, extras = {}, condition = 'present') {
+    const now = s.clock.now();
+    return { success: true, condition, query: s.query, poll_count: s.polls, duration_ms: now - s.start,
+        stable_duration_ms: stable, ...extras, matchSource, timestamp: now, type, observed_state: s.observed ?? null };
+}
+export const legacySleep = (ms, clock = systemClock) => clock.sleep(ms);

package/dist/interact/waits/legacy-wait.js

@@ -0,0 +1,48 @@
+import { checkDebuggerGuard } from '../../debugger/guard.js';
+import { createLegacyWait, legacySleep } from './legacy-wait-state.js';
+import { legacyBaseline, legacyUI, legacyScreen, legacyIdle } from './legacy-wait-observations.js';
+import { legacyLog } from './legacy-log-wait.js';
+async function sample(s, deps) {
+    s.polls++;
+    const now = s.clock.now();
+    if (s.type === 'ui')
+        return legacyUI(s, deps);
+    if (s.type === 'log')
+        return legacyLog(s, deps);
+    if (s.type === 'screen')
+        return legacyScreen(s, deps, now);
+    if (s.type === 'idle')
+        return legacyIdle(s, deps);
+    return null;
+}
+export async function waitForUICore(input, deps) {
+    const state = createLegacyWait(input, deps.clock);
+    await legacyBaseline(state, deps);
+    state.lastChange = state.clock.now();
+    state.previous = state.initial;
+    if (typeof state.observationDelayMs === 'number' && state.observationDelayMs > 0) {
+        try {
+            console.log(`waitForUI: delaying observation for ${state.observationDelayMs}ms`);
+        }
+        catch { /* Best effort. */ }
+        await legacySleep(state.observationDelayMs, state.clock);
+    }
+    while (state.clock.now() <= state.deadline) {
+        const result = await sample(state, deps);
+        if (result)
+            return result;
+        await legacySleep(state.interval, state.clock);
+    }
+    let snapshot = null;
+    if (state.includeSnapshotOnFailure) {
+        try {
+            snapshot = await deps.snapshot({ reason: `wait_for_ui timeout for ${state.type}`, includeLogs: true, ...state.target });
+        }
+        catch (error) {
+            checkDebuggerGuard();
+            snapshot = { error: error instanceof Error ? error.message : String(error) };
+        }
+    }
+    return { success: false, condition: state.match, query: state.query, poll_count: state.polls,
+        duration_ms: state.clock.now() - state.start, stable_duration_ms: state.duration, error: 'Timeout waiting for condition', snapshot, observed_state: state.observed ?? null };
+}

package/dist/interact/waits/screen-wait.js

@@ -0,0 +1,49 @@
+import { systemClock } from '../../runtime/clock.js';
+import { checkDebuggerGuard } from '../../debugger/guard.js';
+async function sample(s, input, interval, deps) {
+    const response = await deps.fingerprint({ platform: input.platform, deviceId: input.deviceId });
+    const fingerprint = response?.fingerprint ?? null;
+    s.activity = response?.activity ?? s.activity;
+    if (fingerprint == null) {
+        s.fingerprint = null;
+        await s.clock.sleep(interval);
+        return 'continue';
+    }
+    s.fingerprint = fingerprint;
+    if (fingerprint === input.previousFingerprint)
+        return null;
+    await s.clock.sleep(interval);
+    try {
+        const confirm = await deps.fingerprint({ platform: input.platform, deviceId: input.deviceId });
+        const confirmed = confirm?.fingerprint ?? null;
+        s.activity = confirm?.activity ?? s.activity;
+        if (confirmed === fingerprint)
+            return { success: true, previousFingerprint: input.previousFingerprint, newFingerprint: fingerprint,
+                elapsedMs: s.clock.now() - s.start, observed_screen: { fingerprint, activity: s.activity } };
+        s.fingerprint = confirmed;
+    }
+    catch (error) {
+        checkDebuggerGuard();
+        console.error('Error confirming fingerprint:', error);
+    }
+    return 'continue';
+}
+export async function waitForScreenChange({ platform, previousFingerprint, timeoutMs = 5000, pollIntervalMs = 300, deviceId }, deps) {
+    const state = { clock: deps.clock ?? systemClock, start: (deps.clock ?? systemClock).now(), fingerprint: null, activity: null };
+    while (state.clock.now() - state.start < timeoutMs) {
+        try {
+            const result = await sample(state, { platform, previousFingerprint, deviceId }, pollIntervalMs, deps);
+            if (result === 'continue')
+                continue;
+            if (result)
+                return result;
+        }
+        catch (error) {
+            checkDebuggerGuard();
+            console.error('Error getting screen fingerprint:', error);
+        }
+        await state.clock.sleep(pollIntervalMs);
+    }
+    return { success: false, reason: 'timeout', previousFingerprint, lastFingerprint: state.fingerprint,
+        elapsedMs: state.clock.now() - state.start, observed_screen: { fingerprint: state.fingerprint, activity: state.activity } };
+}

package/dist/interact/waits/ui-change-helpers.js

@@ -0,0 +1,157 @@
+import { computeSnapshotSignature } from '../../observe/snapshot-metadata.js';
+const _uiChangeKinds = ['hierarchy_diff', 'text_change', 'state_change'];
+import { _normalize, _normalizeBounds, _hash, _resolveParentIndex } from '../targeting/element-helpers.js';
+export function _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 = childIndices(elements, element, index);
+        for (const childIndex of directChildren) {
+            if (!visited.has(childIndex))
+                stack.push(childIndex);
+        }
+    }
+    return result.sort((left, right) => left - right);
+}
+export function _changeIdentityForElement(el, index) {
+    const stableId = _normalize(el.stable_id);
+    if (stableId)
+        return `stable:${stableId}`;
+    return `fallback:${_hash({
+        text: _normalize(el.text ?? el.label ?? el.value ?? ''),
+        contentDescription: _normalize(el.contentDescription ?? el.contentDesc ?? el.accessibilityLabel ?? ''),
+        resourceId: _normalize(el.resourceId ?? el.resourceID ?? el.id ?? ''),
+        type: _normalize(el.type ?? el.class ?? ''),
+        bounds: _normalizeBounds(el.bounds) ?? [0, 0, 0, 0],
+        index
+    })}`;
+}
+export function _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 = _changeIdentityForElement(element, i);
+            map.set(key, _hash({
+                text: _normalize(element.text ?? element.label ?? element.value ?? ''),
+                contentDescription: _normalize(element.contentDescription ?? element.contentDesc ?? element.accessibilityLabel ?? ''),
+                resourceId: _normalize(element.resourceId ?? element.resourceID ?? element.id ?? ''),
+                type: _normalize(element.type ?? element.class ?? ''),
+                bounds: _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
+    };
+}
+export function _buildUiChangeSignatures(tree) {
+    const elements = Array.isArray(tree?.elements) ? tree.elements : [];
+    const textPayload = [];
+    const statePayload = [];
+    for (const el of elements) {
+        textPayload.push(textSignature(el));
+        statePayload.push(stateSignature(el));
+    }
+    return {
+        hierarchy: computeSnapshotSignature(tree),
+        text: _hash({
+            screen: _normalize(tree?.screen),
+            elements: textPayload
+        }),
+        state: _hash({
+            screen: _normalize(tree?.screen),
+            elements: statePayload
+        })
+    };
+}
+export function _matchesUiChange(expected, initial, current) {
+    const candidates = expected ? [expected] : _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;
+}
+export function _uiChangeSignaturesEqual(left, right) {
+    return left.hierarchy === right.hierarchy && left.text === right.text && left.state === right.state;
+}
+function childIndices(elements, element, index) {
+    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 (_resolveParentIndex(elements, elements[i]?.parentId) === index) {
+            directChildren.add(i);
+        }
+    }
+    return directChildren;
+}
+function textSignature(el) {
+    return {
+        text: _normalize(el?.text ?? el?.label ?? el?.value ?? ''),
+        contentDescription: _normalize(el?.contentDescription ?? el?.contentDesc ?? el?.accessibilityLabel ?? ''),
+        resourceId: _normalize(el?.resourceId ?? el?.resourceID ?? el?.id ?? '')
+    };
+}
+function stateSignature(el) {
+    const state = el?.state ?? {};
+    return {
+        checked: state.checked ?? null,
+        selected: state.selected ?? null,
+        focused: state.focused ?? null,
+        expanded: state.expanded ?? null,
+        enabled: state.enabled ?? null,
+        text_value: state.text_value ?? null,
+        value: state.value ?? null,
+        raw_value: state.raw_value ?? null,
+        value_range: state.value_range ?? null
+    };
+}

package/dist/interact/waits/ui-change-state.js

@@ -0,0 +1,18 @@
+import { systemClock } from '../../runtime/clock.js';
+import { currentReadinessWait } from '../../observe/readiness.js';
+export function createChangeWait({ platform, deviceId, timeout_ms = 60000, stability_window_ms = 300, expected_change, scope = 'screen', target = null }, clock = systemClock) {
+    const tracker = currentReadinessWait(), start = clock.now();
+    return { clock, input: { platform, deviceId, timeout_ms, expected_change, scope, target }, tracker, start,
+        stability: Math.max(0, typeof stability_window_ms === 'number' ? stability_window_ms : 300), baseline: null,
+        baselineScope: null, revision: null, loading: null,
+        age: null, candidate: null, change: null,
+        since: null, summary: null,
+        scope: { 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' } };
+}
+export function changeResult(s, success, reason) {
+    return { success, observed_change: success ? s.change : null, snapshot_revision: s.revision ?? undefined,
+        snapshot_freshness_ms: s.age ?? null, timeout: !success, elapsed_ms: s.clock.now() - s.start,
+        expected_change: s.input.expected_change, loading_state: s.loading ?? null, scope: s.scope.scope, target: s.scope.target,
+        stability_state: success ? 'stable' : 'transient', change_summary: s.summary, reason };
+}

package/dist/interact/waits/ui-change-wait.js

@@ -0,0 +1,77 @@
+import { systemClock } from '../../runtime/clock.js';
+import { remainingBudget } from '../../utils/operation-budget.js';
+import { checkDebuggerGuard } from '../../debugger/guard.js';
+import { observeReadinessWait, isDeviceUnavailable } from '../../observe/readiness.js';
+import { readinessDelay } from '../../observe/readiness-service.js';
+import { _buildUiChangeSignatures, _summarizeUiChangeDelta, _matchesUiChange, _uiChangeSignaturesEqual } from './ui-change-helpers.js';
+import { createChangeWait, changeResult } from './ui-change-state.js';
+function scopeFailure(s, tree, scoped) {
+    s.scope = scoped.resolution;
+    return { success: false, observed_change: null, snapshot_revision: typeof tree?.snapshot_revision === 'number' ? tree.snapshot_revision : s.revision ?? undefined,
+        snapshot_freshness_ms: typeof tree?.captured_at_ms === 'number' ? Math.max(0, s.clock.now() - tree.captured_at_ms) : s.age ?? null,
+        timeout: true, elapsed_ms: s.clock.now() - s.start, expected_change: s.input.expected_change, loading_state: tree?.loading_state ?? s.loading ?? null,
+        scope: scoped.resolution.scope, target: scoped.resolution.target, stability_state: 'transient', change_summary: s.summary, reason: scoped.error.message, error: scoped.error };
+}
+function changed(s, signatures) {
+    const change = _matchesUiChange(s.input.expected_change, s.baseline, signatures);
+    if (!change) {
+        s.candidate = null;
+        s.change = null;
+        s.since = null;
+        return false;
+    }
+    if (!s.candidate || !_uiChangeSignaturesEqual(s.candidate, signatures) || s.change !== change) {
+        s.candidate = signatures;
+        s.change = change;
+        s.since = s.clock.now();
+    }
+    const stable = s.since === null ? 0 : s.clock.now() - s.since;
+    return (s.stability === 0 || stable >= s.stability) && (!s.tracker || s.tracker.summary.state === 'settled');
+}
+async function sample(s, deps) {
+    if (s.tracker)
+        remainingBudget();
+    const started = s.clock.now(), a = s.input;
+    const tree = await deps.observe({ platform: a.platform, deviceId: a.deviceId });
+    observeReadinessWait(tree, started);
+    const scoped = deps.scope(tree, a.scope, a.target);
+    if (scoped.error)
+        return scopeFailure(s, tree, scoped);
+    const signatures = _buildUiChangeSignatures({ ...tree, elements: scoped.elements });
+    s.revision = typeof tree?.snapshot_revision === 'number' ? tree.snapshot_revision : s.revision;
+    s.loading = tree?.loading_state ?? s.loading;
+    s.age = typeof tree?.captured_at_ms === 'number' ? Math.max(0, s.clock.now() - tree.captured_at_ms) : s.age;
+    s.summary = s.baseline ? _summarizeUiChangeDelta(s.baselineScope?.elements ?? [], scoped.elements) : s.summary;
+    s.scope = scoped.resolution;
+    s.baselineScope = s.baselineScope ?? scoped;
+    if (!s.baseline) {
+        s.baseline = signatures;
+        s.baselineScope = scoped;
+    }
+    else if (changed(s, signatures))
+        return changeResult(s, true, 'UI change observed');
+    return null;
+}
+export async function waitForUIChange(input, deps) {
+    const state = createChangeWait(input, deps.clock);
+    while (state.clock.now() - state.start < state.input.timeout_ms) {
+        try {
+            const result = await sample(state, deps);
+            if (result)
+                return result;
+        }
+        catch (error) {
+            checkDebuggerGuard();
+            if (state.tracker && !String(error).includes('READINESS_'))
+                state.tracker.unavailable();
+            if (state.tracker && isDeviceUnavailable(error))
+                throw error;
+            if (state.tracker && String(error).includes('ACTION_TIMEOUT')) {
+                state.tracker.deadline();
+                break;
+            }
+        }
+        await (state.tracker && state.clock === systemClock ? readinessDelay(300) : state.clock.sleep(300));
+    }
+    return changeResult(state, false, 'timeout');
+}

package/dist/interact/waits/ui-wait-condition.js

@@ -0,0 +1,56 @@
+import { _normalize, _isVisibleElement, _resolveActionableAncestor } from '../targeting/element-helpers.js';
+function matchesField(value, query, contains) {
+    if (query === undefined || query === null)
+        return true;
+    return contains ? _normalize(value).includes(_normalize(query)) : _normalize(value) === _normalize(query);
+}
+export function matchingElements(elements, selector) {
+    const matches = [];
+    const contains = !!selector.contains;
+    for (let idx = 0; idx < elements.length; idx++) {
+        const el = elements[idx];
+        if (!matchesField(el.text || el.label || el.value || '', selector.text, contains))
+            continue;
+        if (!matchesField(el.resourceId || el.resourceID || el.id || '', selector.resource_id, contains))
+            continue;
+        if (!matchesField(el.contentDescription || el.contentDesc || el.accessibilityLabel || el.label || '', selector.accessibility_id, contains))
+            continue;
+        matches.push({ el, idx });
+    }
+    return matches;
+}
+function selectedMatch(matches, index) {
+    if (!matches.length)
+        return null;
+    return index === undefined ? matches[0] : index >= 0 && index < matches.length ? matches[index] : null;
+}
+function clickTarget(elements, chosen, tap) {
+    if (!chosen)
+        return null;
+    if (tap && (!_isVisibleElement(chosen.el) || chosen.el.enabled === false))
+        return chosen;
+    return _resolveActionableAncestor(elements, chosen) || chosen;
+}
+export function evaluateCondition(elements, matches, condition, index, tap = false) {
+    const chosen = selectedMatch(matches, index);
+    let element = chosen;
+    let met = false;
+    if (condition === 'exists')
+        met = index !== undefined ? chosen !== null : matches.length >= 1;
+    else if (condition === 'not_exists')
+        met = index !== undefined ? chosen === null : matches.length === 0;
+    else if (condition === 'visible')
+        met = !!chosen && waitVisible(chosen.el);
+    else if (condition === 'clickable') {
+        element = clickTarget(elements, chosen, tap);
+        met = !!element && waitVisible(element.el) && !!element.el.enabled && !!(element.el.clickable || element.el._interactable || element.el.focusable);
+    }
+    if (tap && met && element && _isVisibleElement(element.el) && element.el.enabled !== false) {
+        element = _resolveActionableAncestor(elements, element) ?? element;
+    }
+    return { met, element };
+}
+function waitVisible(el) {
+    const b = el.bounds;
+    return !!el.visible && Array.isArray(b) && b.length >= 4 && b[2] > b[0] && b[3] > b[1];
+}

package/dist/interact/waits/ui-wait-state.js

@@ -0,0 +1,38 @@
+import { systemClock } from '../../runtime/clock.js';
+import { currentReadinessWait } from '../../observe/readiness.js';
+export function createUIWait(input, clock = systemClock) {
+    const tracker = currentReadinessWait(), start = clock.now();
+    const requestedIndex = typeof input.match?.index === 'number' ? input.match.index : null;
+    const args = { condition: 'exists', timeout_ms: 60000, poll_interval_ms: 300,
+        retry: { max_attempts: 1, backoff_ms: 0 }, singleObservation: false, singleAttempt: false,
+        rejectAmbiguous: false, resolveTapTarget: false, ...input };
+    // Explicit undefined values have the same defaults as destructured handler parameters.
+    if (args.condition === undefined)
+        args.condition = 'exists';
+    if (args.timeout_ms === undefined)
+        args.timeout_ms = 60000;
+    if (args.poll_interval_ms === undefined)
+        args.poll_interval_ms = 300;
+    if (args.retry === undefined)
+        args.retry = { max_attempts: 1, backoff_ms: 0 };
+    const requested = { selector: args.selector ?? {}, condition: args.condition, match: requestedIndex === null ? null : { index: requestedIndex } };
+    return { clock, args, requestedIndex, requested, tracker, start, attempts: 0, polls: 0,
+        count: 0, element: null, met: false, stable: 0 };
+}
+export function waitObserved(s, condition = s.met) {
+    return { matched_count: s.count, condition_satisfied: condition, selected_index: s.element?.index ?? null, last_matched_element: s.element };
+}
+export function waitFailure(s, code, message, observed = waitObserved(s, false)) {
+    return { status: 'timeout', error: { code, message }, metrics: { latency_ms: s.clock.now() - s.start, poll_count: s.polls, attempts: s.attempts }, requested: s.requested, observed };
+}
+export function validateUIWait(s) {
+    const { selector, condition, platform } = s.args;
+    const valid = [selector?.text, selector?.resource_id, selector?.accessibility_id].some(value => typeof value === 'string' && value.trim().length > 0);
+    if (!valid)
+        return waitFailure(s, 'INVALID_SELECTOR', 'Selector must include at least one non-empty field: text, resource_id, or accessibility_id');
+    if (!['exists', 'not_exists', 'visible', 'clickable'].includes(condition))
+        return waitFailure(s, 'INVALID_CONDITION', `Unsupported condition: ${condition}`);
+    if (platform && !['android', 'ios'].includes(platform))
+        return waitFailure(s, 'PLATFORM_NOT_SUPPORTED', `Unsupported platform: ${platform}`);
+    return null;
+}