mobile-debug-mcp 0.34.0 → 0.36.0

package/dist/interact/input-service.js

@@ -0,0 +1 @@
+export {};

package/dist/interact/interaction-trace.js

@@ -0,0 +1,21 @@
+import { systemClock } from '../runtime/clock.js';
+import { createTraceStep, nextActionId } from '../runtime/action-results.js';
+export function buildObservationTrace({ actionType, stage, success, attempts, metadata }, clock = systemClock) {
+    const now = clock.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))
+    };
+}

package/dist/interact/model.js

@@ -0,0 +1 @@
+export {};

package/dist/interact/observation.js

@@ -0,0 +1 @@
+export {};

package/dist/interact/targeting/candidate-ancestor.js

@@ -0,0 +1,58 @@
+import { _isSemanticActionable } from './element-helpers.js';
+import { nearbyControl } from './nearby-control.js';
+function parentOf(elements, parent) {
+    const index = typeof parent === 'number' ? parent : /^\d+$/.test(parent) ? Number(parent) : null;
+    if (index !== null && elements[index])
+        return { el: elements[index], idx: index };
+    if (typeof parent !== 'string')
+        return null;
+    const found = elements.findIndex(el => el.resourceId === parent || el.id === parent);
+    return found >= 0 && elements[found] ? { el: elements[found], idx: found } : null;
+}
+function ancestor(elements, chosen) {
+    if (!Array.isArray(chosen.el.bounds) || chosen.el.parentId == null)
+        return null;
+    let current = chosen, safety = 0;
+    while (safety < 20 && !(current.el.clickable || current.el.focusable) && current.el.parentId != null) {
+        const parent = parentOf(elements, current.el.parentId);
+        if (!parent)
+            break;
+        current = parent;
+        if (current.el.clickable || current.el.enabled || current.el.focusable)
+            return current;
+        safety++;
+    }
+    return null;
+}
+function containing(elements, chosen) {
+    const child = chosen.el.bounds;
+    if (!Array.isArray(child))
+        return null;
+    let best = null, area = Infinity;
+    for (let idx = 0; idx < elements.length; idx++) {
+        const el = elements[idx];
+        if (!el || !(el.clickable || el.focusable) || !Array.isArray(el.bounds) || el.bounds.length < 4)
+            continue;
+        const [l, t, r, b] = el.bounds;
+        if (l <= child[0] && t <= child[1] && r >= child[2] && b >= child[3]) {
+            const size = (r - l) * (b - t);
+            if (size < area) {
+                area = size;
+                best = { el, idx };
+            }
+        }
+    }
+    return best;
+}
+export function preferActionable(best, elements, screen) {
+    const parent = ancestor(elements, best) ?? containing(elements, best);
+    if (parent)
+        best = { ...parent, score: Math.min(1, best.score + .02), reason: 'clickable_parent_preferred', interactable: true };
+    if (!(best.el.clickable || best.el.focusable || _isSemanticActionable(best.el))) {
+        const nearby = nearbyControl(elements, best, screen);
+        if (nearby)
+            best = { el: nearby.el, idx: nearby.idx, score: Math.min(1, best.score + .02),
+                reason: nearby.sliderLike ? 'slider_track_preferred' : 'nearby_actionable_control', interactable: true };
+    }
+    return best;
+}

package/dist/interact/targeting/candidate-result.js

@@ -0,0 +1,23 @@
+import { _summarizeResolutionCandidate } from './element-helpers.js';
+export function candidateResult(best, candidates) {
+    const b = best.el.bounds;
+    const bounds = Array.isArray(b) ? { left: b[0], top: b[1], right: b[2], bottom: b[3] } : null;
+    const unique = candidates.filter((candidate, index, array) => index === array.findIndex(other => other.idx === candidate.idx && other.el === candidate.el));
+    const alternates = unique.filter(candidate => candidate.idx !== best.idx || candidate.el !== best.el).slice(0, 3).map(_summarizeResolutionCandidate);
+    const element = {
+        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, 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: bounds ? { x: Math.floor((bounds.left + bounds.right) / 2), y: Math.floor((bounds.top + bounds.bottom) / 2) } : null,
+        telemetry: { matchedIndex: best.idx ?? null, matchedInteractable: !!best.interactable, sliderLike: best.reason === 'slider_track_preferred' }
+    };
+    if (best.reason === 'slider_track_preferred')
+        element.interactionHint = { kind: 'slider',
+            axis: bounds && (bounds.bottom - bounds.top) > (bounds.right - bounds.left) ? 'vertical' : 'horizontal', trackBounds: bounds };
+    const score = Math.min(1, Number(best.score.toFixed(3)));
+    return { found: true, element, score, confidence: score, resolution: {
+            confidence: score, reason: best.reason, fallback_available: alternates.length > 0, matched_count: unique.length, alternates
+        } };
+}

package/dist/interact/targeting/candidate-scoring.js

@@ -0,0 +1,50 @@
+import { _normalize, _isSemanticActionable } from './element-helpers.js';
+function textScore(el, query, exact) {
+    const text = _normalize(el.text ?? el.label ?? el.value ?? '');
+    const content = _normalize(el.contentDescription ?? el.contentDesc ?? el.accessibilityLabel ?? '');
+    const resource = _normalize(el.resourceId ?? el.resourceID ?? el.id ?? '');
+    const type = _normalize(el.type ?? el.class ?? '');
+    const choices = [
+        [text, text === query, 1, 'exact_text_match'], [content, content === query, .95, 'exact_content_desc_match'],
+        [resource, resource === query, .92, 'exact_resource_id_match']
+    ];
+    if (!exact)
+        choices.push([text, text.includes(query), .6, 'partial_text_match'], [content, content.includes(query), .55, 'partial_content_desc_match'], [resource, resource.includes(query), .7, 'partial_resource_id_match']);
+    choices.push([type, exact ? type === query : type.includes(query), .3, exact ? 'exact_class_match' : 'partial_class_match']);
+    for (const [value, matched, score, reason] of choices)
+        if (value && matched)
+            return { score, reason };
+    return { score: 0, reason: 'best_scoring_candidate' };
+}
+function semanticScore(el, query, exact, initial) {
+    const role = _normalize(el.semantic?.semantic_role ?? '');
+    const actions = Array.isArray(el.semantic?.supported_actions) ? el.semantic.supported_actions.map(_normalize).filter(Boolean) : [];
+    const result = { ...initial };
+    if (!result.score && role && (exact ? role === query : role.includes(query))) {
+        result.score = .5;
+        result.reason = 'semantic_role_match';
+    }
+    if (actions.some(action => exact ? action === query : action.includes(query))) {
+        result.score = Math.max(result.score, result.score > 0 ? .65 : .6);
+        result.reason = 'semantic_action_match';
+    }
+    if (!exact && result.score === 0 && el.semantic?.adjustable && /slider|stepper|dropdown|segment|control|adjust/.test(query)) {
+        result.score = .45;
+        result.reason = 'semantic_control_match';
+    }
+    return result;
+}
+export function scoreCandidate(el, idx, query, exact) {
+    if (!el || !el.visible)
+        return null;
+    const bounds = el.bounds || [0, 0, 0, 0];
+    if (!Array.isArray(bounds) || bounds.length < 4)
+        return null;
+    if (bounds[2] <= bounds[0] || bounds[3] <= bounds[1])
+        return null;
+    const interactable = !!(el.clickable || el.enabled || el.focusable || _isSemanticActionable(el));
+    const result = semanticScore(el, query, exact, textScore(el, query, exact));
+    if (result.score > 0 && interactable)
+        result.score += .05;
+    return result.score > 0 ? { el, idx, ...result, interactable } : null;
+}

package/dist/interact/targeting/element-helpers.js

@@ -0,0 +1,216 @@
+import { createHash } from 'node:crypto';
+export function _normalize(s) {
+    if (s === null || s === undefined)
+        return '';
+    try {
+        return String(s).toLowerCase().trim();
+    }
+    catch {
+        return '';
+    }
+}
+export function _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;
+}
+export function _hash(value) {
+    return createHash('sha256').update(JSON.stringify(value)).digest('hex');
+}
+function matchesField(value, query, contains) {
+    if (query === undefined || query === null)
+        return true;
+    const normalized = _normalize(query);
+    return contains ? value.includes(normalized) : value === normalized;
+}
+export function _matchesSelector(el, selector) {
+    if (!selector)
+        return false;
+    const contains = !!selector.contains;
+    return matchesField(_normalize(el.text ?? el.label ?? el.value ?? ''), selector.text, contains) &&
+        matchesField(_normalize(el.resourceId ?? el.resourceID ?? el.id ?? ''), selector.resource_id, contains) &&
+        matchesField(_normalize(el.contentDescription ?? el.contentDesc ?? el.accessibilityLabel ?? el.label ?? ''), selector.accessibility_id, contains);
+}
+export function _findFirstMatchingElement(elements, selector) {
+    if (!selector)
+        return null;
+    for (let i = 0; i < elements.length; i++) {
+        const el = elements[i];
+        if (!el)
+            continue;
+        if (_matchesSelector(el, selector))
+            return { el, idx: i };
+    }
+    return null;
+}
+export function _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 = _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 _normalize(el.resourceId ?? el.resourceID ?? el.id ?? '') === normalized ||
+                _normalize(el.stable_id ?? '') === normalized;
+        });
+        return foundIndex >= 0 ? foundIndex : null;
+    }
+    return null;
+}
+export function _isVisibleElement(el) {
+    const bounds = _normalizeBounds(el.bounds);
+    return !!el.visible && !!bounds && bounds[2] > bounds[0] && bounds[3] > bounds[1];
+}
+export function _isTapActionable(el, storedStableId, platform) {
+    if (!_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) => _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 };
+}
+export function _isAdjustableActionable(el, storedStableId) {
+    if (!_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 };
+}
+export function _computeElementId(platform, deviceId, el, index) {
+    const identity = {
+        platform,
+        deviceId: deviceId || '',
+        text: _normalize(el.text ?? el.label ?? el.value ?? ''),
+        resourceId: _normalize(el.resourceId ?? el.resourceID ?? el.id ?? ''),
+        accessibilityId: _normalize(el.contentDescription ?? el.contentDesc ?? el.accessibilityLabel ?? el.label ?? ''),
+        class: _normalize(el.type ?? el.class ?? ''),
+        bounds: _normalizeBounds(el.bounds) ?? [0, 0, 0, 0],
+        index
+    };
+    return `el_${createHash('sha1').update(JSON.stringify(identity)).digest('hex').slice(0, 24)}`;
+}
+export function _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: _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
+    };
+}
+export function _summarizeResolutionCandidate(candidate) {
+    const bounds = _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
+    };
+}
+export function _isAdjustableControl(el) {
+    if (!el)
+        return false;
+    const type = _normalize(el.type ?? el.class ?? '');
+    const role = _normalize(el.role ?? '');
+    return !!el.state?.value_range || /slider|seekbar|stepper|adjustable|range/.test(type) || /slider|seekbar|stepper|adjustable|range/.test(role);
+}
+export function _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;
+}
+export function _resolveActionableAncestor(elements, chosen) {
+    if (!chosen)
+        return null;
+    if (hasActionableTrait(chosen.el))
+        return chosen;
+    let current = chosen;
+    let safety = 0;
+    while (safety < 20 && !(hasActionableTrait(current.el)) && current.el.parentId !== undefined && current.el.parentId !== null) {
+        const parentIndex = _resolveParentIndex(elements, current.el.parentId);
+        if (parentIndex !== null && elements[parentIndex]) {
+            current = { el: elements[parentIndex], idx: parentIndex };
+            if (hasActionableTrait(current.el))
+                return current;
+        }
+        else {
+            break;
+        }
+        safety++;
+    }
+    const childBounds = _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 || !(hasActionableTrait(el)))
+            continue;
+        const bounds = _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;
+}
+function hasActionableTrait(el) {
+    return !!(el.clickable || el.focusable || _isSemanticActionable(el));
+}

package/dist/interact/targeting/find-element.js

@@ -0,0 +1,65 @@
+import { systemClock } from '../../runtime/clock.js';
+import { _normalize } from './element-helpers.js';
+import { checkDebuggerGuard } from '../../debugger/guard.js';
+import { scoreCandidate } from './candidate-scoring.js';
+import { preferActionable } from './candidate-ancestor.js';
+import { candidateResult } from './candidate-result.js';
+function scoreTree(search, tree, query, exact) {
+    if (!tree || !Array.isArray(tree.elements))
+        return;
+    const candidates = [];
+    let improved = false;
+    for (let i = 0; i < tree.elements.length; i++) {
+        try {
+            const candidate = scoreCandidate(tree.elements[i], i, query, exact);
+            if (!candidate)
+                continue;
+            candidates.push(candidate);
+            if (!search.best || candidate.score > search.best.score) {
+                search.best = candidate;
+                search.tree = tree;
+                improved = true;
+                if (candidate.score >= .95) {
+                    search.stop = true;
+                    break;
+                }
+            }
+        }
+        catch (error) {
+            checkDebuggerGuard();
+            console.error('Error scoring element:', error);
+        }
+    }
+    if (improved)
+        search.candidates = candidates.slice();
+}
+export async function findElement({ query, exact = false, timeoutMs = 3000, platform, deviceId }, observe, clock = systemClock) {
+    const start = clock.now(), deadline = start + timeoutMs, normalized = _normalize(query);
+    if (!normalized)
+        return { found: false, error: 'Empty query' };
+    const search = { best: null, tree: null, candidates: [], stop: false };
+    while (clock.now() <= deadline) {
+        try {
+            scoreTree(search, await observe({ platform, deviceId }), normalized, exact);
+        }
+        catch (error) {
+            checkDebuggerGuard();
+            console.error('Error fetching UI tree:', error);
+        }
+        if (search.stop || clock.now() > deadline)
+            break;
+        await clock.sleep(100);
+    }
+    if (!search.best)
+        return { found: false, error: 'Element not found' };
+    try {
+        const elements = search.tree && Array.isArray(search.tree.elements) ? search.tree.elements : [];
+        const screen = search.tree?.resolution && typeof search.tree.resolution === 'object' ? search.tree.resolution : null;
+        search.best = preferActionable(search.best, elements, screen);
+    }
+    catch (error) {
+        checkDebuggerGuard();
+        console.error('Error resolving ancestor:', error);
+    }
+    return candidateResult(search.best, search.candidates);
+}

package/dist/interact/targeting/nearby-control.js

@@ -0,0 +1,56 @@
+import { _normalize, _normalizeBounds } from './element-helpers.js';
+function trackLimits(label, screen) {
+    const width = Number(screen?.width) > 0 ? Number(screen?.width) : 0;
+    const height = Number(screen?.height) > 0 ? Number(screen?.height) : 0;
+    return { length: Math.max(220, width > 0 ? Math.floor(width * .18) : 0, height > 0 ? Math.floor(height * .18) : 0),
+        thickness: Math.max(180, width > 0 ? Math.floor(width * .08) : 0, height > 0 ? Math.floor(height * .08) : 0),
+        labelWidth: label[2] - label[0], labelHeight: label[3] - label[1] };
+}
+function nearbyScore(el, label, limits) {
+    if (!el || !(el.clickable || el.focusable) || el.visible === false)
+        return null;
+    const b = _normalizeBounds(el.bounds);
+    if (!b)
+        return null;
+    const width = b[2] - b[0], height = b[3] - b[1], gap = b[1] - label[3];
+    if (gap < -32 || gap > 640 || Math.min(label[2], b[2]) - Math.max(label[0], b[0]) < -32)
+        return null;
+    const horizontal = width >= Math.max(limits.length, Math.floor(limits.labelWidth * 1.5)) && height <= limits.thickness;
+    const vertical = height >= Math.max(limits.length, Math.floor(limits.labelHeight * 1.5)) && width <= limits.thickness;
+    const sliderLike = /slider|seek|range/i.test(_normalize(el.type ?? el.class ?? '')) || horizontal || vertical;
+    return { score: appearanceScore(gap, el, width, limits.labelWidth, sliderLike), sliderLike };
+}
+function appearanceScore(gap, el, width, labelWidth, sliderLike) {
+    const text = _normalize(el.text ?? el.label ?? el.value ?? '');
+    const content = _normalize(el.contentDescription ?? el.contentDesc ?? el.accessibilityLabel ?? '');
+    const type = _normalize(el.type ?? el.class ?? '');
+    let score = gap;
+    if (!text && !content)
+        score -= 18;
+    if (sliderLike)
+        score -= 30;
+    if (/view|layout|group|frame/i.test(type))
+        score -= 10;
+    if (width > labelWidth * 1.5)
+        score -= 8;
+    if (text || content)
+        score += 20;
+    return score;
+}
+export function nearbyControl(elements, chosen, screen) {
+    if (!chosen)
+        return null;
+    const label = _normalizeBounds(chosen.el.bounds);
+    if (!label)
+        return null;
+    const limits = trackLimits(label, screen);
+    let best = null, score = Infinity;
+    for (let i = chosen.idx + 1; i < Math.min(elements.length, chosen.idx + 8); i++) {
+        const candidate = nearbyScore(elements[i], label, limits);
+        if (candidate && candidate.score < score) {
+            score = candidate.score;
+            best = { el: elements[i], idx: i, sliderLike: candidate.sliderLike };
+        }
+    }
+    return best;
+}

package/dist/interact/targeting/resolved-elements.js

@@ -0,0 +1,21 @@
+/** Bounded, insertion-ordered handles; repeated observations refresh retention order. */
+export class ResolvedElements {
+    maximum;
+    elements = new Map();
+    constructor(maximum = 256) {
+        this.maximum = maximum;
+    }
+    get(id) { return this.elements.get(id); }
+    clear() { this.elements.clear(); }
+    remember(id, context) {
+        if (this.elements.has(id))
+            this.elements.delete(id);
+        this.elements.set(id, context);
+        while (this.elements.size > this.maximum) {
+            const oldest = this.elements.keys().next().value;
+            if (!oldest)
+                break;
+            this.elements.delete(oldest);
+        }
+    }
+}

package/dist/interact/targeting/tap-target.js

@@ -0,0 +1,17 @@
+import { _isTapActionable, _normalizeBounds } from './element-helpers.js';
+export function resolveTap(tree, stored, deps) {
+    const platform = tree?.device?.platform === 'ios' ? 'ios' : stored.platform;
+    const deviceId = tree?.device?.id || stored.deviceId;
+    const elements = Array.isArray(tree?.elements) ? tree.elements : [];
+    const current = deps.current(elements, platform, deviceId, stored);
+    if (!current)
+        return { failure: 'STALE_REFERENCE', target: null };
+    const target = deps.target(current.el, current.index);
+    const actionable = _isTapActionable(current.el, stored.stable_id, stored.platform);
+    if (!actionable.actionable)
+        return { failure: actionable.failureCode ?? 'ELEMENT_NOT_INTERACTABLE', target };
+    const bounds = _normalizeBounds(current.el.bounds) ?? stored.bounds;
+    if (!bounds || bounds[2] <= bounds[0] || bounds[3] <= bounds[1])
+        return { failure: 'ELEMENT_NOT_INTERACTABLE', target };
+    return { target, point: { x: Math.floor((bounds[0] + bounds[2]) / 2), y: Math.floor((bounds[1] + bounds[3]) / 2) } };
+}

package/dist/interact/targeting/target-scope.js

@@ -0,0 +1,104 @@
+import { _normalize, _computeElementId } from './element-helpers.js';
+import { _collectSubtreeIndices } from '../waits/ui-change-helpers.js';
+export function findScopedElement(tree, targetElementId, store) {
+    const elements = Array.isArray(tree?.elements) ? tree.elements : [];
+    const platform = tree?.device?.platform === 'ios' ? 'ios' : 'android';
+    const deviceId = tree?.device?.id ?? undefined;
+    const normalizedTarget = _normalize(targetElementId);
+    for (let i = 0; i < elements.length; i++) {
+        const el = elements[i];
+        if (!el)
+            continue;
+        const computedElementId = _computeElementId(platform, deviceId, el, i);
+        if (computedElementId === targetElementId) {
+            return {
+                index: i,
+                stableId: el.stable_id ?? null,
+                reason: 'element_id_match'
+            };
+        }
+    }
+    const directStable = findStableElement(elements, normalizedTarget, 'stable_id_match');
+    if (directStable)
+        return directStable;
+    const storedContext = store.get(targetElementId);
+    return storedContext?.stable_id
+        ? findStableElement(elements, _normalize(storedContext.stable_id), 'stored_stable_id_match')
+        : null;
+}
+export function resolveUiChangeScope(tree, scope, target, find) {
+    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 = find(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 = _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
+        }
+    };
+}
+function findStableElement(elements, normalizedTarget, reason) {
+    for (let i = 0; i < elements.length; i++) {
+        const el = elements[i];
+        if (!el?.stable_id)
+            continue;
+        if (_normalize(el.stable_id) === normalizedTarget)
+            return { index: i, stableId: el.stable_id, reason };
+    }
+    return null;
+}