mobile-debug-mcp 0.30.0 → 0.30.2

package/src/interact/index.ts

@@ -43,6 +43,7 @@ interface UiElement {
   focusable?: boolean
   visible?: boolean
   parentId?: number | string | null
+  children?: number[]
   _index?: number
   _interactable?: boolean
   _sliderLike?: boolean
@@ -52,6 +53,10 @@ interface UiElement {
   test_tag?: string | null
   selector?: { value: string | null, confidence: { score: number, reason: string } | null } | null
   semantic?: UIElementSemanticMetadata | null
+  actions?: string[] | null
+  accessibilityActions?: string[] | null
+  runtimeActions?: string[] | null
+  platformActions?: string[] | null
 }
 
 interface ResolvedUiElementContext {
@@ -60,6 +65,7 @@ interface ResolvedUiElementContext {
   deviceId?: string
   bounds: [number, number, number, number] | null
   index: number
+  stable_id?: string | null
 }
 
 interface UiResolution {
@@ -73,6 +79,24 @@ interface UiChangeSignatureSet {
   state: string | null
 }
 
+interface UiChangeScopeResolution {
+  scope: 'screen' | 'subtree'
+  target: string | null
+  resolved: boolean
+  resolvedIndex: number | null
+  resolvedStableId: string | null
+  reason: string
+}
+
+interface UiChangeScopeResult {
+  elements: UiElement[]
+  resolution: UiChangeScopeResolution
+  error?: {
+    code: 'INVALID_SCOPE' | 'ELEMENT_NOT_FOUND'
+    message: string
+  }
+}
+
 interface RankedResolutionCandidate {
   el: UiElement
   idx: number
@@ -81,6 +105,15 @@ interface RankedResolutionCandidate {
   interactable: boolean
 }
 
+interface InferredLabeledSliderState {
+  current: number
+  min: number
+  max: number
+  value_range: { min: number; max: number }
+  touch_bounds: [number, number, number, number]
+  source: 'nearby_labels'
+}
+
 function buildObservationTrace({
   actionType,
   stage,
@@ -201,11 +234,88 @@ export class ToolsInteract {
     return null
   }
 
+  private static _resolveParentIndex(elements: UiElement[], parentId: number | string | null | undefined): number | null {
+    if (parentId === undefined || parentId === null) return null
+
+    if (typeof parentId === 'number' && Number.isInteger(parentId) && parentId >= 0 && parentId < elements.length) {
+      return parentId
+    }
+
+    if (typeof parentId === 'string') {
+      const normalized = ToolsInteract._normalize(parentId)
+      if (!normalized) return null
+
+      if (/^\d+$/.test(normalized)) {
+        const index = Number(normalized)
+        if (index >= 0 && index < elements.length) return index
+      }
+
+      const foundIndex = elements.findIndex((el) => {
+        if (!el) return false
+        return ToolsInteract._normalize(el.resourceId ?? el.resourceID ?? el.id ?? '') === normalized ||
+          ToolsInteract._normalize(el.stable_id ?? '') === normalized
+      })
+
+      return foundIndex >= 0 ? foundIndex : null
+    }
+
+    return null
+  }
+
   private static _isVisibleElement(el: UiElement): boolean {
     const bounds = ToolsInteract._normalizeBounds(el.bounds)
     return !!el.visible && !!bounds && bounds[2] > bounds[0] && bounds[3] > bounds[1]
   }
 
+  private static _isTapActionable(
+    el: UiElement,
+    storedStableId?: string | null,
+    platform?: 'android' | 'ios'
+  ): { actionable: boolean, failureCode?: ActionFailureCode, reason?: string } {
+    if (!ToolsInteract._isVisibleElement(el)) {
+      return { actionable: false, failureCode: 'ELEMENT_NOT_INTERACTABLE', reason: 'element is not visible' }
+    }
+
+    if (el.enabled === false) {
+      return { actionable: false, failureCode: 'ELEMENT_NOT_INTERACTABLE', reason: 'element is disabled' }
+    }
+
+    const semanticTapActionable = !!el.semantic && (
+      el.semantic.is_clickable ||
+      (Array.isArray(el.semantic.supported_actions) && el.semantic.supported_actions.some((action) => ToolsInteract._normalize(action) === 'tap'))
+    )
+
+    if (!el.clickable && !(platform === 'ios' && semanticTapActionable)) {
+      return { actionable: false, failureCode: 'ELEMENT_NOT_INTERACTABLE', reason: 'element is not clickable' }
+    }
+
+    if (storedStableId) {
+      if (!el.stable_id || el.stable_id !== storedStableId) {
+        return { actionable: false, failureCode: 'STALE_REFERENCE', reason: 'element stable_id changed' }
+      }
+    }
+
+    return { actionable: true }
+  }
+
+  private static _isAdjustableActionable(el: UiElement, storedStableId?: string | null): { actionable: boolean, failureCode?: ActionFailureCode, reason?: string } {
+    if (!ToolsInteract._isVisibleElement(el)) {
+      return { actionable: false, failureCode: 'ELEMENT_NOT_INTERACTABLE', reason: 'element is not visible' }
+    }
+
+    if (el.enabled === false) {
+      return { actionable: false, failureCode: 'ELEMENT_NOT_INTERACTABLE', reason: 'element is disabled' }
+    }
+
+    if (storedStableId) {
+      if (!el.stable_id || el.stable_id !== storedStableId) {
+        return { actionable: false, failureCode: 'STALE_REFERENCE', reason: 'element stable_id changed' }
+      }
+    }
+
+    return { actionable: true }
+  }
+
   private static _computeElementId(platform: 'android' | 'ios', deviceId: string | undefined, el: UiElement, index: number): string {
     const identity = {
       platform,
@@ -229,7 +339,8 @@ export class ToolsInteract {
       platform,
       deviceId,
       bounds,
-      index
+      index,
+      stable_id: el.stable_id ?? null
     })
 
     return {
@@ -249,6 +360,235 @@ export class ToolsInteract {
     }
   }
 
+  private static _resolveUiChangeScope(
+    tree: any,
+    scope: 'screen' | 'subtree' | undefined,
+    target: string | null | undefined
+  ): UiChangeScopeResult {
+    const elements = Array.isArray(tree?.elements) ? tree.elements as UiElement[] : []
+    const normalizedScope = scope === 'subtree' ? 'subtree' : 'screen'
+
+    if (normalizedScope === 'screen') {
+      return {
+        elements,
+        resolution: {
+          scope: 'screen',
+          target: null,
+          resolved: true,
+          resolvedIndex: null,
+          resolvedStableId: null,
+          reason: 'screen scope'
+        }
+      }
+    }
+
+    const requestedTarget = typeof target === 'string' && target.trim().length > 0 ? target.trim() : null
+    if (!requestedTarget) {
+      return {
+        elements: [],
+        resolution: {
+          scope: 'subtree',
+          target: null,
+          resolved: false,
+          resolvedIndex: null,
+          resolvedStableId: null,
+          reason: 'subtree scope requires a target element id'
+        },
+        error: {
+          code: 'INVALID_SCOPE',
+          message: 'scope=subtree requires a target element_id'
+        }
+      }
+    }
+
+    const resolved = ToolsInteract._findScopedElement(tree, requestedTarget)
+    if (!resolved) {
+      return {
+        elements: [],
+        resolution: {
+          scope: 'subtree',
+          target: requestedTarget,
+          resolved: false,
+          resolvedIndex: null,
+          resolvedStableId: null,
+          reason: 'target element could not be resolved'
+        },
+        error: {
+          code: 'ELEMENT_NOT_FOUND',
+          message: `Target element ${requestedTarget} could not be resolved for subtree scope`
+        }
+      }
+    }
+
+    const subtreeIndices = ToolsInteract._collectSubtreeIndices(elements, resolved.index)
+    const scopedElements = subtreeIndices.map((index) => elements[index]).filter((element): element is UiElement => !!element)
+
+    return {
+      elements: scopedElements,
+      resolution: {
+        scope: 'subtree',
+        target: requestedTarget,
+        resolved: true,
+        resolvedIndex: resolved.index,
+        resolvedStableId: resolved.stableId,
+        reason: resolved.reason
+      }
+    }
+  }
+
+  private static _findScopedElement(tree: any, targetElementId: string): { index: number, stableId: string | null, reason: string } | null {
+    const elements = Array.isArray(tree?.elements) ? tree.elements as UiElement[] : []
+    const platform = tree?.device?.platform === 'ios' ? 'ios' : 'android'
+    const deviceId = tree?.device?.id ?? undefined
+    const normalizedTarget = ToolsInteract._normalize(targetElementId)
+
+    for (let i = 0; i < elements.length; i++) {
+      const el = elements[i]
+      if (!el) continue
+
+      const computedElementId = ToolsInteract._computeElementId(platform, deviceId, el, i)
+      if (computedElementId === targetElementId) {
+        return {
+          index: i,
+          stableId: el.stable_id ?? null,
+          reason: 'element_id_match'
+        }
+      }
+    }
+
+    for (let i = 0; i < elements.length; i++) {
+      const el = elements[i]
+      if (!el) continue
+
+      if (el.stable_id && ToolsInteract._normalize(el.stable_id) === normalizedTarget) {
+        return {
+          index: i,
+          stableId: el.stable_id,
+          reason: 'stable_id_match'
+        }
+      }
+    }
+
+    const storedContext = ToolsInteract._resolvedUiElements.get(targetElementId)
+    if (storedContext?.stable_id) {
+      const normalizedStoredStableId = ToolsInteract._normalize(storedContext.stable_id)
+      for (let i = 0; i < elements.length; i++) {
+        const el = elements[i]
+        if (!el?.stable_id) continue
+        if (ToolsInteract._normalize(el.stable_id) === normalizedStoredStableId) {
+          return {
+            index: i,
+            stableId: el.stable_id,
+            reason: 'stored_stable_id_match'
+          }
+        }
+      }
+    }
+
+    return null
+  }
+
+  private static _collectSubtreeIndices(elements: UiElement[], rootIndex: number): number[] {
+    if (!Array.isArray(elements) || rootIndex < 0 || rootIndex >= elements.length) return []
+
+    const visited = new Set<number>()
+    const stack = [rootIndex]
+    const result: number[] = []
+
+    while (stack.length > 0) {
+      const index = stack.pop()
+      if (index === undefined || visited.has(index) || index < 0 || index >= elements.length) continue
+      visited.add(index)
+      result.push(index)
+
+      const element = elements[index]
+      if (!element) continue
+
+      const directChildren = new Set<number>()
+      if (Array.isArray(element.children)) {
+        for (const childIndex of element.children) {
+          if (typeof childIndex === 'number' && Number.isInteger(childIndex) && childIndex >= 0 && childIndex < elements.length) {
+            directChildren.add(childIndex)
+          }
+        }
+      }
+
+      for (let i = 0; i < elements.length; i++) {
+        if (ToolsInteract._resolveParentIndex(elements, elements[i]?.parentId) === index) {
+          directChildren.add(i)
+        }
+      }
+
+      for (const childIndex of directChildren) {
+        if (!visited.has(childIndex)) stack.push(childIndex)
+      }
+    }
+
+    return result.sort((left, right) => left - right)
+  }
+
+  private static _changeIdentityForElement(el: UiElement, index: number): string {
+    const stableId = ToolsInteract._normalize(el.stable_id)
+    if (stableId) return `stable:${stableId}`
+
+    return `fallback:${ToolsInteract._hash({
+      text: ToolsInteract._normalize(el.text ?? el.label ?? el.value ?? ''),
+      contentDescription: ToolsInteract._normalize(el.contentDescription ?? el.contentDesc ?? el.accessibilityLabel ?? ''),
+      resourceId: ToolsInteract._normalize(el.resourceId ?? el.resourceID ?? el.id ?? ''),
+      type: ToolsInteract._normalize(el.type ?? el.class ?? ''),
+      bounds: ToolsInteract._normalizeBounds(el.bounds) ?? [0, 0, 0, 0],
+      index
+    })}`
+  }
+
+  private static _summarizeUiChangeDelta(initialElements: UiElement[], currentElements: UiElement[]) {
+    const buildMap = (elements: UiElement[]) => {
+      const map = new Map<string, string>()
+      for (let i = 0; i < elements.length; i++) {
+        const element = elements[i]
+        if (!element) continue
+        const key = ToolsInteract._changeIdentityForElement(element, i)
+        map.set(key, ToolsInteract._hash({
+          text: ToolsInteract._normalize(element.text ?? element.label ?? element.value ?? ''),
+          contentDescription: ToolsInteract._normalize(element.contentDescription ?? element.contentDesc ?? element.accessibilityLabel ?? ''),
+          resourceId: ToolsInteract._normalize(element.resourceId ?? element.resourceID ?? element.id ?? ''),
+          type: ToolsInteract._normalize(element.type ?? element.class ?? ''),
+          bounds: ToolsInteract._normalizeBounds(element.bounds) ?? [0, 0, 0, 0],
+          state: element.state ?? null,
+          visible: !!element.visible,
+          enabled: !!element.enabled,
+          clickable: !!element.clickable
+        }))
+      }
+      return map
+    }
+
+    const initialMap = buildMap(initialElements)
+    const currentMap = buildMap(currentElements)
+    let added = 0
+    let removed = 0
+    let mutated = 0
+
+    for (const [key, value] of currentMap.entries()) {
+      if (!initialMap.has(key)) {
+        added++
+      } else if (initialMap.get(key) !== value) {
+        mutated++
+      }
+    }
+
+    for (const key of initialMap.keys()) {
+      if (!currentMap.has(key)) removed++
+    }
+
+    return {
+      total_elements: currentElements.length,
+      added_elements: added,
+      removed_elements: removed,
+      mutated_elements: mutated
+    }
+  }
+
   private static _rememberResolvedElement(elementId: string, context: ResolvedUiElementContext) {
     if (ToolsInteract._resolvedUiElements.has(elementId)) {
       ToolsInteract._resolvedUiElements.delete(elementId)
@@ -392,13 +732,217 @@ export class ToolsInteract {
     if (!el?.state) return null
     const stateValue = el.state[property as keyof UIElementState]
     if (typeof stateValue === 'number' && Number.isFinite(stateValue)) return stateValue
+    const parsedStateValue = ToolsInteract._parseNumericControlValue(stateValue)
+    if (parsedStateValue !== null) return parsedStateValue
     if (property === 'value' || property === 'raw_value') {
       const fallback = el.state.raw_value ?? el.state.value
       if (typeof fallback === 'number' && Number.isFinite(fallback)) return fallback
+      return ToolsInteract._parseNumericControlValue(fallback)
+    }
+    return null
+  }
+
+  private static _parseNumericControlValue(value: unknown): number | null {
+    if (typeof value === 'number' && Number.isFinite(value)) return value
+    if (typeof value !== 'string') return null
+    const trimmed = value.trim()
+    if (!trimmed) return null
+
+    const percent = trimmed.match(/^([-+]?\d+(?:\.\d+)?)\s*%$/)
+    if (percent) return Number(percent[1])
+
+    const fraction = trimmed.match(/^([-+]?\d+(?:\.\d+)?)\s+of\s+[-+]?\d+(?:\.\d+)?$/i)
+    if (fraction) return Number(fraction[1])
+
+    const plain = Number(trimmed)
+    if (Number.isFinite(plain)) return plain
+
+    const trailing = trimmed.match(/,\s*([-+]?\d+(?:\.\d+)?)$/)
+    if (trailing) return Number(trailing[1])
+
+    return null
+  }
+
+  private static _readNumericControlRange(el: UiElement | null): { min: number; max: number } | null {
+    const min = typeof el?.state?.value_range?.min === 'number' ? el.state.value_range.min : null
+    const max = typeof el?.state?.value_range?.max === 'number' ? el.state.value_range.max : null
+    if (min !== null && max !== null && Number.isFinite(min) && Number.isFinite(max) && max > min) {
+      return { min, max }
+    }
+
+    const value = el?.state?.value ?? el?.state?.raw_value
+    if (typeof value === 'string') {
+      const fraction = value.trim().match(/^[-+]?\d+(?:\.\d+)?\s+of\s+([-+]?\d+(?:\.\d+)?)$/i)
+      if (fraction) {
+        const parsedMax = Number(fraction[1])
+        if (Number.isFinite(parsedMax) && parsedMax > 0) return { min: 0, max: parsedMax }
+      }
+    }
+
+    return null
+  }
+
+  private static _readControlStep(el: UiElement | null): number | null {
+    const candidates = [
+      el?.state?.step,
+      el?.state?.value_range?.step
+    ]
+    for (const candidate of candidates) {
+      if (typeof candidate === 'number' && Number.isFinite(candidate) && candidate > 0) return candidate
     }
     return null
   }
 
+  private static _quantizeTargetValue(targetValue: number, min: number, max: number, step: number | null): number {
+    if (!step) return targetValue
+    const quantized = min + (Math.round((targetValue - min) / step) * step)
+    const bounded = Math.max(min, Math.min(max, quantized))
+    const precision = ToolsInteract._decimalPrecisionForStep(step)
+    return Number(bounded.toFixed(precision))
+  }
+
+  private static _decimalPrecisionForStep(step: number): number {
+    const normalized = String(step).toLowerCase()
+    const [coefficient, exponentPart] = normalized.split('e')
+    const coefficientDecimals = coefficient.includes('.')
+      ? coefficient.split('.')[1]?.length ?? 0
+      : 0
+    const exponent = exponentPart !== undefined ? Number(exponentPart) : 0
+    const precision = exponent < 0
+      ? coefficientDecimals + Math.abs(exponent)
+      : Math.max(0, coefficientDecimals - exponent)
+    return Math.max(0, Math.min(12, precision))
+  }
+
+  private static _defaultAdjustTolerance(range: { min: number; max: number } | null, step: number | null): number {
+    if (step) return 0
+    if (!range) return 0
+    return Math.max(0, 0.01 * Math.abs(range.max - range.min))
+  }
+
+  private static _runtimeActionSet(el: UiElement | null): Set<string> {
+    const values = [
+      ...(Array.isArray(el?.actions) ? el!.actions! : []),
+      ...(Array.isArray(el?.accessibilityActions) ? el!.accessibilityActions! : []),
+      ...(Array.isArray(el?.runtimeActions) ? el!.runtimeActions! : []),
+      ...(Array.isArray(el?.platformActions) ? el!.platformActions! : [])
+    ]
+    return new Set(values.map((value) => ToolsInteract._normalize(value)).filter(Boolean))
+  }
+
+  private static _hasDirectAdjustmentAction(el: UiElement | null): boolean {
+    const actions = ToolsInteract._runtimeActionSet(el)
+    return [
+      'action_set_progress',
+      'set_progress',
+      'setprogress',
+      'semanticsactions.setprogress',
+      'set_value',
+      'setvalue',
+      'direct_set_value'
+    ].some((action) => actions.has(action))
+  }
+
+  private static _adjustmentDirections(el: UiElement | null): { increment: boolean; decrement: boolean } {
+    const actions = ToolsInteract._runtimeActionSet(el)
+    return {
+      increment: ['increment', 'accessibility_increment', 'action_increment'].some((action) => actions.has(action)),
+      decrement: ['decrement', 'accessibility_decrement', 'action_decrement'].some((action) => actions.has(action))
+    }
+  }
+
+  private static _textFromElement(el: UiElement | null): string {
+    return String(el?.text ?? el?.contentDescription ?? el?.contentDesc ?? el?.accessibilityLabel ?? el?.value ?? '').trim()
+  }
+
+  private static _parseLeadingNumber(text: string): number | null {
+    const match = text.trim().match(/^([-+]?\d+(?:\.\d+)?)(?:\s*[a-zA-Z%]+)?$/)
+    if (!match) return null
+    const value = Number(match[1])
+    return Number.isFinite(value) ? value : null
+  }
+
+  private static _inferLabeledSliderState(elements: UiElement[], track: UiElement | null): InferredLabeledSliderState | null {
+    const trackBounds = ToolsInteract._normalizeBounds(track?.bounds)
+    if (!track || !trackBounds) return null
+    const type = ToolsInteract._normalize(track.type ?? track.class ?? '')
+    const role = ToolsInteract._normalize(track.role ?? '')
+    const width = trackBounds[2] - trackBounds[0]
+    const height = trackBounds[3] - trackBounds[1]
+    const wideTrackLike = width >= 240 && height <= 220
+    const knownTrackLike = /slider|seekbar|range/.test(type) || /slider|range/.test(role)
+    if (!wideTrackLike && !knownTrackLike) return null
+
+    const trackTop = trackBounds[1]
+    const trackBottom = trackBounds[3]
+    const trackCenterX = (trackBounds[0] + trackBounds[2]) / 2
+    const labels = elements
+      .map((el, index) => {
+        const bounds = ToolsInteract._normalizeBounds(el.bounds)
+        const text = ToolsInteract._textFromElement(el)
+        const value = ToolsInteract._parseLeadingNumber(text)
+        return bounds && text && value !== null
+          ? {
+            index,
+            el,
+            text,
+            value,
+            bounds,
+            centerX: (bounds[0] + bounds[2]) / 2,
+            centerY: (bounds[1] + bounds[3]) / 2,
+            hasUnit: /[a-zA-Z%]/.test(text)
+          }
+          : null
+      })
+      .filter((label): label is NonNullable<typeof label> => !!label)
+
+    const rangeLabels = labels
+      .filter((label) => {
+        const verticallyNearTrack = label.centerY >= trackTop - 520 && label.centerY <= trackBottom + 260
+        const horizontallyNearTrack = label.centerX >= trackBounds[0] - 120 && label.centerX <= trackBounds[2] + 120
+        return verticallyNearTrack && horizontallyNearTrack && label.hasUnit
+      })
+      .sort((a, b) => a.centerX - b.centerX)
+
+    if (rangeLabels.length < 2) return null
+    const minLabel = rangeLabels[0]
+    const maxLabel = rangeLabels[rangeLabels.length - 1]
+    if (!minLabel || !maxLabel || maxLabel.value <= minLabel.value) return null
+
+    const currentCandidates = labels
+      .filter((label) => {
+        if (label.index === minLabel.index || label.index === maxLabel.index) return false
+        if (label.value < minLabel.value || label.value > maxLabel.value) return false
+        if (label.centerY < trackTop - 950 || label.centerY > minLabel.centerY - 20) return false
+        return label.centerX >= trackCenterX - 80
+      })
+      .sort((a, b) => {
+        const yDistance = Math.abs((trackTop - 420) - a.centerY) - Math.abs((trackTop - 420) - b.centerY)
+        if (yDistance !== 0) return yDistance
+        return b.centerX - a.centerX
+      })
+
+    const currentLabel = currentCandidates[0]
+    if (!currentLabel) return null
+
+    const candidateBelowRangeLabels = minLabel.centerY < trackTop && maxLabel.centerY < trackTop
+    const labelDerivedBounds: [number, number, number, number] = [
+      Math.min(minLabel.bounds[0], trackBounds[0]),
+      Math.max(currentLabel.bounds[3] + 12, Math.min(minLabel.bounds[1], maxLabel.bounds[1]) - 160),
+      Math.max(maxLabel.bounds[2], trackBounds[2]),
+      Math.max(currentLabel.bounds[3] + 80, Math.min(minLabel.bounds[1], maxLabel.bounds[1]) - 32)
+    ]
+
+    return {
+      current: currentLabel.value,
+      min: minLabel.value,
+      max: maxLabel.value,
+      value_range: { min: minLabel.value, max: maxLabel.value },
+      touch_bounds: candidateBelowRangeLabels ? labelDerivedBounds : trackBounds,
+      source: 'nearby_labels'
+    }
+  }
+
   private static _buildControlPoint(bounds: [number, number, number, number], ratio: number, axis: 'horizontal' | 'vertical') {
     const clampedRatio = Math.max(0, Math.min(1, ratio))
     const [left, top, right, bottom] = bounds
@@ -565,20 +1109,11 @@ export class ToolsInteract {
     let safety = 0
 
     while (safety < 20 && current.el && !(current.el.clickable || current.el.focusable || ToolsInteract._isSemanticActionable(current.el)) && current.el.parentId !== undefined && current.el.parentId !== null) {
-      const parentId = current.el.parentId
-      let parentIndex: number | null = null
-
-      if (typeof parentId === 'number') parentIndex = parentId
-      else if (typeof parentId === 'string' && /^\d+$/.test(parentId)) parentIndex = Number(parentId)
+      const parentIndex = ToolsInteract._resolveParentIndex(elements, current.el.parentId)
 
       if (parentIndex !== null && elements[parentIndex]) {
         current = { el: elements[parentIndex], idx: parentIndex }
         if (current.el.clickable || current.el.focusable || ToolsInteract._isSemanticActionable(current.el)) return current
-      } else if (typeof parentId === 'string') {
-        const foundIndex = elements.findIndex((el) => el.resourceId === parentId || el.id === parentId)
-        if (foundIndex === -1) break
-        current = { el: elements[foundIndex], idx: foundIndex }
-        if (current.el.clickable || current.el.focusable || ToolsInteract._isSemanticActionable(current.el)) return current
       } else {
         break
       }
@@ -718,12 +1253,16 @@ export class ToolsInteract {
 
     const resolvedTarget = ToolsInteract._resolvedTargetFromElement(resolved.elementId, currentMatch.el, currentMatch.index)
 
-    if (!ToolsInteract._isVisibleElement(currentMatch.el)) {
-      return ToolsInteract._actionFailure(actionType, selector, resolvedTarget, 'ELEMENT_NOT_INTERACTABLE', true, fingerprintBefore)
-    }
-
-    if (currentMatch.el.enabled === false) {
-      return ToolsInteract._actionFailure(actionType, selector, resolvedTarget, 'ELEMENT_NOT_INTERACTABLE', true, fingerprintBefore)
+    const tapActionability = ToolsInteract._isTapActionable(currentMatch.el, resolved.stable_id, resolved.platform)
+    if (!tapActionability.actionable) {
+      return ToolsInteract._actionFailure(
+        actionType,
+        selector,
+        resolvedTarget,
+        tapActionability.failureCode ?? 'ELEMENT_NOT_INTERACTABLE',
+        true,
+        fingerprintBefore
+      )
     }
 
     const bounds = ToolsInteract._normalizeBounds(currentMatch.el.bounds) ?? resolved.bounds
@@ -758,8 +1297,8 @@ export class ToolsInteract {
     element_id,
     property = 'value',
     targetValue,
-    tolerance = 0,
-    maxAttempts = 3,
+    tolerance,
+    maxAttempts,
     platform,
     deviceId
   }: {
@@ -774,11 +1313,14 @@ export class ToolsInteract {
   }): Promise<AdjustControlResponse> {
     const actionType = 'adjust_control'
     const targetSelector = selector ?? (element_id ? { elementId: element_id } : null)
-    const normalizedTolerance = Number.isFinite(tolerance) ? Math.max(0, tolerance) : 0
-    const attemptsLimit = Math.max(1, Math.floor(Number(maxAttempts) || 1))
+    const requestedTolerance = typeof tolerance === 'number' && Number.isFinite(tolerance) ? Math.max(0, tolerance) : null
+    const attemptsLimit = maxAttempts === undefined || maxAttempts === null
+      ? 5
+      : Math.max(1, Math.floor(Number(maxAttempts) || 1))
     const sourcePlatform: 'android' | 'ios' = platform || 'android'
     let resolvedPlatform = sourcePlatform
     let resolvedDeviceId = deviceId
+    const storedResolvedTarget = element_id ? ToolsInteract._resolvedUiElements.get(element_id) ?? null : null
     const fingerprintBefore = await ToolsInteract._captureFingerprint(resolvedPlatform, resolvedDeviceId)
     let semanticFallbackElement: FindElementResponse['element'] | null = null
     const traceSteps: TraceStep[] = []
@@ -825,6 +1367,7 @@ export class ToolsInteract {
           retry_depth: attempts
         })
       }
+      const responseTolerance = requestedTolerance ?? 0
       const base = buildActionExecutionResult({
         actionType,
         sourceModule: 'interact',
@@ -837,7 +1380,7 @@ export class ToolsInteract {
         failure: { failureCode, retryable },
         details: {
           target_value: targetValue,
-          tolerance: normalizedTolerance,
+          tolerance: responseTolerance,
           property,
           attempts,
           adjustment_mode: adjustmentMode,
@@ -854,7 +1397,7 @@ export class ToolsInteract {
         target_state: {
           property,
           target_value: targetValue,
-          tolerance: normalizedTolerance
+          tolerance: responseTolerance
         },
         actual_state: actualState,
         within_tolerance: false,
@@ -972,8 +1515,8 @@ export class ToolsInteract {
       return null
     }
 
-    if (!selector && !element_id) {
-      return buildFailure('ELEMENT_NOT_FOUND', 'selector or element_id is required', null, undefined, null, 0, 'gesture', false)
+    if ((!selector && !element_id) || (selector && element_id)) {
+      return buildFailure('ELEMENT_NOT_FOUND', 'exactly one of selector or element_id is required', null, undefined, null, 0, 'gesture', false)
     }
 
     if (selector && !element_id) {
@@ -1035,8 +1578,10 @@ export class ToolsInteract {
     let currentDevice: any = undefined
     let attemptCount = 0
     let cachedResolvedMatch: { el: UiElement, idx: number } | null = null
+    let coordinateTapsAwaitingFreshGesture = false
 
-    for (let attempt = 0; attempt < attemptsLimit; attempt++) {
+    adjustmentAttempts:
+    for (let attempt = 0; attempt < attemptsLimit && attemptCount < attemptsLimit; attempt++) {
       const resolved: {
         tree: any
         device: any
@@ -1062,11 +1607,44 @@ export class ToolsInteract {
       resolvedTarget = resolved.resolvedTarget
       const currentEl: UiElement = resolved.match.el
       cachedResolvedMatch = resolved.match
-      const bounds = ToolsInteract._normalizeBounds(currentEl.bounds)
-      const valueRange = currentEl.state?.value_range ?? null
-      const currentValue = ToolsInteract._readNumericControlValue(currentEl, property)
+
+      const adjustableActionability = ToolsInteract._isAdjustableActionable(currentEl, storedResolvedTarget?.stable_id)
+      if (!adjustableActionability.actionable) {
+        return buildFailure(
+          adjustableActionability.failureCode ?? 'ELEMENT_NOT_INTERACTABLE',
+          adjustableActionability.reason ?? 'adjustable control is not actionable',
+          resolvedTarget,
+          currentDevice,
+          lastObservedState,
+          attemptCount,
+          lastAdjustmentMode,
+          true
+        )
+      }
+
+      const elementsForInference = Array.isArray(resolved.tree?.elements)
+        ? resolved.tree.elements as UiElement[]
+        : cachedResolvedMatch
+          ? [cachedResolvedMatch.el]
+          : [currentEl]
+      const inferredSliderState = ToolsInteract._inferLabeledSliderState(elementsForInference, currentEl)
+      const nativeBounds = ToolsInteract._normalizeBounds(currentEl.bounds)
+      const bounds = inferredSliderState?.touch_bounds ?? nativeBounds
+      const valueRange = ToolsInteract._readNumericControlRange(currentEl) ?? inferredSliderState?.value_range ?? null
+      const step = ToolsInteract._readControlStep(currentEl)
+      const normalizedTargetValue = valueRange
+        ? ToolsInteract._quantizeTargetValue(targetValue, valueRange.min, valueRange.max, step)
+        : targetValue
+      const effectiveTolerance = requestedTolerance ?? ToolsInteract._defaultAdjustTolerance(valueRange, step)
+      const currentValue = ToolsInteract._readNumericControlValue(currentEl, property) ?? inferredSliderState?.current ?? null
       const actualState = currentValue !== null
-        ? { property, value: currentValue, raw_value: typeof currentEl.state?.raw_value === 'number' ? currentEl.state.raw_value : undefined }
+        ? {
+          property,
+          value: currentValue,
+          raw_value: typeof currentEl.state?.raw_value === 'number'
+            ? currentEl.state.raw_value
+            : inferredSliderState?.current
+        }
         : null
 
       lastObservedState = actualState
@@ -1083,10 +1661,23 @@ export class ToolsInteract {
         return buildFailure('ELEMENT_NOT_INTERACTABLE', 'adjust_control currently supports numeric value and raw_value properties only', resolvedTarget, currentDevice, actualState, attemptCount, lastAdjustmentMode, false)
       }
 
-      if (currentValue !== null && Math.abs(currentValue - targetValue) <= normalizedTolerance) {
+      const isAdjustableControl = ToolsInteract._isAdjustableControl(currentEl) || !!inferredSliderState
+      if (!isAdjustableControl) {
+        return buildFailure('ELEMENT_NOT_INTERACTABLE', 'target is not an adjustable control', resolvedTarget, currentDevice, actualState, attemptCount, lastAdjustmentMode, false)
+      }
+
+      if (currentValue === null) {
+        return buildFailure('UNKNOWN', 'current numeric value is unavailable', resolvedTarget, currentDevice, actualState, attemptCount, lastAdjustmentMode, false)
+      }
+
+      if (valueRange && (targetValue < valueRange.min || targetValue > valueRange.max)) {
+        return buildFailure('CONTROL_CONVERGENCE_FAILED', `targetValue ${targetValue} is outside the control range ${valueRange.min}..${valueRange.max}`, resolvedTarget, currentDevice, actualState, attemptCount, lastAdjustmentMode, false)
+      }
+
+      if (currentValue !== null && Math.abs(currentValue - normalizedTargetValue) <= effectiveTolerance) {
         recordTraceStep('verify', 'success', {
           property,
-          target_value: targetValue,
+          target_value: normalizedTargetValue,
           actual_state: actualState,
           reason: 'control already within tolerance'
         })
@@ -1101,8 +1692,8 @@ export class ToolsInteract {
           uiFingerprintBefore: fingerprintBefore,
           uiFingerprintAfter,
           details: {
-            target_value: targetValue,
-            tolerance: normalizedTolerance,
+            target_value: normalizedTargetValue,
+            tolerance: effectiveTolerance,
             property,
             attempts: attemptCount,
             adjustment_mode: 'semantic',
@@ -1118,8 +1709,8 @@ export class ToolsInteract {
           ...base,
           target_state: {
             property,
-            target_value: targetValue,
-            tolerance: normalizedTolerance
+            target_value: normalizedTargetValue,
+            tolerance: effectiveTolerance
           },
           actual_state: actualState,
           within_tolerance: true,
@@ -1129,50 +1720,48 @@ export class ToolsInteract {
         }
       }
 
-      if (!ToolsInteract._isAdjustableControl(currentEl)) {
-        return buildFailure('ELEMENT_NOT_INTERACTABLE', 'target is not an adjustable control', resolvedTarget, currentDevice, actualState, attemptCount, lastAdjustmentMode, false)
-      }
-
       if (!bounds) {
         return buildFailure('ELEMENT_NOT_INTERACTABLE', 'adjustable control has no bounds', resolvedTarget, currentDevice, actualState, attemptCount, lastAdjustmentMode, false)
       }
 
-      const min = typeof valueRange?.min === 'number' ? valueRange.min : null
-      const max = typeof valueRange?.max === 'number' ? valueRange.max : null
-      if (min === null || max === null || !Number.isFinite(min) || !Number.isFinite(max) || max <= min) {
-        return buildFailure('ELEMENT_NOT_INTERACTABLE', 'value_range unavailable', resolvedTarget, currentDevice, actualState, attemptCount, lastAdjustmentMode, false)
-      }
-
-      if (targetValue < min || targetValue > max) {
-        return buildFailure('UNKNOWN', `targetValue ${targetValue} is outside the control range ${min}..${max}`, resolvedTarget, currentDevice, actualState, attemptCount, lastAdjustmentMode, false)
-      }
-
-      const axis = ToolsInteract._controlAxis(currentEl, bounds)
-      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 probePoints = ToolsInteract._buildAdjustmentProbePoints(bounds, targetValue, currentValue, min, max, axis)
-
       const runVerification = async (): Promise<{
         verification: any
         observedState: { property: string; value: number | null; raw_value?: number | null } | null
         withinTolerance: boolean
       }> => {
+        if (inferredSliderState) {
+          const tree = await ToolsObserve.getUITreeHandler({ platform: resolvedPlatform, deviceId: resolvedDeviceId }) as any
+          const elements = Array.isArray(tree?.elements) ? tree.elements as UiElement[] : []
+          const refreshed = ToolsInteract._inferLabeledSliderState(elements, currentEl)
+          const observedValue = refreshed?.current ?? null
+          const observedState = observedValue !== null
+            ? { property, value: observedValue, raw_value: observedValue }
+            : actualState
+
+          return {
+            verification: {
+              success: observedValue !== null && Math.abs(observedValue - normalizedTargetValue) <= effectiveTolerance,
+              observed_state: observedState,
+              reason: observedValue !== null
+                ? 'visible labeled value read from nearby slider labels'
+                : 'visible labeled value unavailable'
+            },
+            observedState,
+            withinTolerance: observedValue !== null && Math.abs(observedValue - normalizedTargetValue) <= effectiveTolerance
+          }
+        }
+
         const verification = await ToolsInteract.expectStateHandler({
           element_id: resolvedTarget?.elementId ?? element_id,
           selector: selector ?? undefined,
           property,
-          expected: targetValue,
+          expected: normalizedTargetValue,
           platform: resolvedPlatform,
           deviceId: resolvedDeviceId
         }) as any
 
-        const observedValue = typeof verification?.observed_state?.value === 'number'
-          ? verification.observed_state.value
-          : typeof verification?.observed_state?.raw_value === 'number'
-            ? verification.observed_state.raw_value
-            : null
+        const observedValue = ToolsInteract._parseNumericControlValue(verification?.observed_state?.value) ??
+          ToolsInteract._parseNumericControlValue(verification?.observed_state?.raw_value)
         const observedState = observedValue !== null
           ? {
             property,
@@ -1184,7 +1773,7 @@ export class ToolsInteract {
         return {
           verification,
           observedState,
-          withinTolerance: observedValue !== null && Math.abs(observedValue - targetValue) <= normalizedTolerance
+          withinTolerance: observedValue !== null && Math.abs(observedValue - normalizedTargetValue) <= effectiveTolerance
         }
       }
 
@@ -1193,86 +1782,276 @@ export class ToolsInteract {
       let verification: any = null
       let verificationResult: any = { verification: null, observedState: actualState, withinTolerance: false }
 
-      for (let i = 0; i < probePoints.length; i++) {
-        const probePoint = probePoints[i]
-        lastAdjustmentMode = 'coordinate'
-        recordTraceStep('execute', 'retry', {
-          attempt: attemptCount + 1,
-          mode: 'coordinate',
-          point: probePoint
-        })
-        const actionResult = await ToolsInteract.tapHandler({
-          platform: resolvedPlatform,
-          x: probePoint.x,
-          y: probePoint.y,
-          deviceId: resolvedDeviceId
-        })
-        attemptCount++
-        actionDevice = actionResult.device ?? actionDevice
+      const directActionSupported = ToolsInteract._hasDirectAdjustmentAction(currentEl)
+      if (directActionSupported && attemptCount < attemptsLimit) {
+        const { interact, resolved: actionResolved } = await ToolsInteract.getInteractionService(resolvedPlatform, resolvedDeviceId)
+        if (typeof interact.setAdjustableValue === 'function') {
+          lastAdjustmentMode = 'semantic'
+          recordTraceStep('execute', 'retry', {
+            attempt: attemptCount + 1,
+            mode: 'semantic',
+            strategy: 'direct_set_value',
+            target_value: normalizedTargetValue
+          })
+          const actionResult = await interact.setAdjustableValue({
+            deviceId: actionResolved.id,
+            target: resolvedTarget,
+            property,
+            value: normalizedTargetValue
+          })
+          attemptCount++
+          actionDevice = actionResult?.device ?? actionDevice
+
+          if (actionResult?.success !== false) {
+            verificationResult = await runVerification()
+            observedState = verificationResult.observedState
+            lastObservedState = observedState
+            recordTraceStep('verify', verificationResult.withinTolerance ? 'success' : 'retry', {
+              attempt: attemptCount,
+              property,
+              target_value: normalizedTargetValue,
+              actual_state: observedState,
+              reason: verificationResult.verification?.reason ?? 'direct adjustment did not converge yet'
+            })
+
+            if (verificationResult.withinTolerance) {
+              const uiFingerprintAfter = await ToolsInteract._captureFingerprint(resolvedPlatform, resolvedDeviceId)
+              const base = buildActionExecutionResult({
+                actionType,
+                sourceModule: 'interact',
+                device: actionDevice ?? currentDevice,
+                selector: targetSelector,
+                resolved: resolvedTarget,
+                success: true,
+                uiFingerprintBefore: fingerprintBefore,
+                uiFingerprintAfter,
+                details: {
+                  target_value: normalizedTargetValue,
+                  tolerance: effectiveTolerance,
+                  property,
+                  attempts: attemptCount,
+                  adjustment_mode: lastAdjustmentMode,
+                  actual_state: observedState,
+                  converged: true,
+                  within_tolerance: true,
+                  reason: verificationResult.verification?.reason ?? 'control converged to target value'
+                },
+                traceSteps
+              }) as AdjustControlResponse
+
+              return {
+                ...base,
+                target_state: {
+                  property,
+                  target_value: normalizedTargetValue,
+                  tolerance: effectiveTolerance
+                },
+                actual_state: observedState,
+                within_tolerance: true,
+                converged: true,
+                attempts: attemptCount,
+                adjustment_mode: lastAdjustmentMode
+              }
+            }
 
-        if (!actionResult.success) {
+            cachedResolvedMatch = null
+            if (attemptCount < attemptsLimit) {
+              continue
+            }
+          }
+        }
+      }
+
+      const directions = ToolsInteract._adjustmentDirections(currentEl)
+      if ((directions.increment || directions.decrement) && attemptCount < attemptsLimit) {
+        const { interact, resolved: actionResolved } = await ToolsInteract.getInteractionService(resolvedPlatform, resolvedDeviceId)
+        const adjustByDirection = typeof interact.adjustAccessibleValue === 'function'
+          ? interact.adjustAccessibleValue.bind(interact)
+          : null
+        while (adjustByDirection && attemptCount < attemptsLimit) {
+          const direction = normalizedTargetValue > (observedState?.value ?? currentValue) ? 'increment' : 'decrement'
+          if ((direction === 'increment' && !directions.increment) || (direction === 'decrement' && !directions.decrement)) break
+          lastAdjustmentMode = 'semantic'
           recordTraceStep('execute', 'retry', {
+            attempt: attemptCount + 1,
+            mode: 'semantic',
+            strategy: 'accessibility_increment_decrement',
+            direction
+          })
+          const actionResult = await adjustByDirection({
+            deviceId: actionResolved.id,
+            target: resolvedTarget,
+            property,
+            direction
+          })
+          attemptCount++
+          actionDevice = actionResult?.device ?? actionDevice
+          if (actionResult?.success === false) break
+
+          verificationResult = await runVerification()
+          observedState = verificationResult.observedState
+          lastObservedState = observedState
+          recordTraceStep('verify', verificationResult.withinTolerance ? 'success' : 'retry', {
             attempt: attemptCount,
-            mode: 'coordinate',
-            point: probePoint,
-            success: false
+            property,
+            target_value: normalizedTargetValue,
+            actual_state: observedState,
+            reason: verificationResult.verification?.reason ?? 'incremental adjustment did not converge yet'
           })
-          continue
+
+          if (verificationResult.withinTolerance) {
+            const uiFingerprintAfter = await ToolsInteract._captureFingerprint(resolvedPlatform, resolvedDeviceId)
+            const base = buildActionExecutionResult({
+              actionType,
+              sourceModule: 'interact',
+              device: actionDevice ?? currentDevice,
+              selector: targetSelector,
+              resolved: resolvedTarget,
+              success: true,
+              uiFingerprintBefore: fingerprintBefore,
+              uiFingerprintAfter,
+              details: {
+                target_value: normalizedTargetValue,
+                tolerance: effectiveTolerance,
+                property,
+                attempts: attemptCount,
+                adjustment_mode: lastAdjustmentMode,
+                actual_state: observedState,
+                converged: true,
+                within_tolerance: true,
+                reason: verificationResult.verification?.reason ?? 'control converged to target value'
+              },
+              traceSteps
+            }) as AdjustControlResponse
+
+            return {
+              ...base,
+              target_state: {
+                property,
+                target_value: normalizedTargetValue,
+                tolerance: effectiveTolerance
+              },
+              actual_state: observedState,
+              within_tolerance: true,
+              converged: true,
+              attempts: attemptCount,
+              adjustment_mode: lastAdjustmentMode
+            }
+          }
+
+          cachedResolvedMatch = null
+          if (attemptCount < attemptsLimit) {
+            continue adjustmentAttempts
+          }
         }
+      }
 
-        verificationResult = await runVerification()
-        observedState = verificationResult.observedState
-        lastObservedState = observedState
-        recordTraceStep('verify', verificationResult.withinTolerance ? 'success' : 'retry', {
-          attempt: attemptCount,
-          property,
-          target_value: targetValue,
-          actual_state: observedState,
-          reason: verificationResult.verification?.reason ?? 'control did not converge yet'
-        })
+      if (!bounds) {
+        return buildFailure('ELEMENT_NOT_INTERACTABLE', 'adjustable control has no bounds', resolvedTarget, currentDevice, actualState, attemptCount, lastAdjustmentMode, false)
+      }
 
-        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,
+      if (!valueRange) {
+        return buildFailure('UNKNOWN', 'value_range unavailable', resolvedTarget, currentDevice, actualState, attemptCount, lastAdjustmentMode, false)
+      }
+
+      const min = valueRange.min
+      const max = valueRange.max
+      const axis = ToolsInteract._controlAxis(currentEl, bounds)
+      const targetPoint = ToolsInteract._buildConservativeControlPoint(bounds, normalizedTargetValue, currentValue, min, max, axis)
+      const currentPoint = ToolsInteract._buildControlPoint(bounds, (currentValue - min) / (max - min), axis)
+      if (!coordinateTapsAwaitingFreshGesture) {
+        const probePoints = inferredSliderState
+          ? [targetPoint]
+          : ToolsInteract._buildAdjustmentProbePoints(bounds, normalizedTargetValue, currentValue, min, max, axis)
+
+        for (let i = 0; i < probePoints.length && attemptCount < attemptsLimit; i++) {
+          const probePoint = probePoints[i]
+          lastAdjustmentMode = 'coordinate'
+          recordTraceStep('execute', 'retry', {
+            attempt: attemptCount + 1,
+            mode: 'coordinate',
+            point: probePoint
+          })
+          const actionResult = await ToolsInteract.tapHandler({
+            platform: resolvedPlatform,
+            x: probePoint.x,
+            y: probePoint.y,
+            deviceId: resolvedDeviceId
+          })
+          attemptCount++
+          actionDevice = actionResult.device ?? actionDevice
+
+          if (!actionResult.success) {
+            recordTraceStep('execute', 'retry', {
+              attempt: attemptCount,
+              mode: 'coordinate',
+              point: probePoint,
+              success: false
+            })
+            continue
+          }
+
+          verificationResult = await runVerification()
+          observedState = verificationResult.observedState
+          lastObservedState = observedState
+          recordTraceStep('verify', verificationResult.withinTolerance ? 'success' : 'retry', {
+            attempt: attemptCount,
+            property,
+            target_value: normalizedTargetValue,
+            actual_state: observedState,
+            reason: verificationResult.verification?.reason ?? 'control did not converge yet'
+          })
+
+          if (verificationResult.withinTolerance) {
+            const uiFingerprintAfter = await ToolsInteract._captureFingerprint(resolvedPlatform, resolvedDeviceId)
+            const base = buildActionExecutionResult({
+              actionType,
+              sourceModule: 'interact',
+              device: actionDevice ?? currentDevice,
+              selector: targetSelector,
+              resolved: resolvedTarget,
+              success: true,
+              uiFingerprintBefore: fingerprintBefore,
+              uiFingerprintAfter,
+              details: {
+                target_value: normalizedTargetValue,
+                tolerance: effectiveTolerance,
+                property,
+                attempts: attemptCount,
+                adjustment_mode: lastAdjustmentMode,
+                actual_state: observedState,
+                converged: true,
+                within_tolerance: true,
+                reason: verificationResult.verification?.reason ?? 'control converged to target value'
+              },
+              traceSteps
+            }) as AdjustControlResponse
+
+            return {
+              ...base,
+              target_state: {
+                property,
+                target_value: normalizedTargetValue,
+                tolerance: effectiveTolerance
+              },
               actual_state: observedState,
-              converged: true,
               within_tolerance: true,
-              reason: verificationResult.verification?.reason ?? 'control converged to target value'
-            },
-            traceSteps
-          }) as AdjustControlResponse
+              converged: true,
+              attempts: attemptCount,
+              adjustment_mode: lastAdjustmentMode
+            }
+          }
 
-          return {
-            ...base,
-            target_state: {
-              property,
-              target_value: targetValue,
-              tolerance: normalizedTolerance
-            },
-            actual_state: observedState,
-            within_tolerance: true,
-            converged: true,
-            attempts: attemptCount,
-            adjustment_mode: lastAdjustmentMode
+          coordinateTapsAwaitingFreshGesture = true
+          cachedResolvedMatch = null
+          if (attemptCount < attemptsLimit) {
+            continue adjustmentAttempts
           }
         }
       }
 
-      if (currentValue !== null) {
+      if (attemptCount < attemptsLimit) {
+        coordinateTapsAwaitingFreshGesture = false
         lastAdjustmentMode = 'gesture'
         recordTraceStep('execute', 'retry', {
           attempt: attemptCount + 1,
@@ -1286,7 +2065,7 @@ export class ToolsInteract {
           y1: currentPoint.y,
           x2: targetPoint.x,
           y2: targetPoint.y,
-          duration: 220,
+          duration: inferredSliderState ? 520 : 220,
           deviceId: resolvedDeviceId
         })
         attemptCount++
@@ -1308,7 +2087,7 @@ export class ToolsInteract {
         recordTraceStep('verify', verificationResult.withinTolerance ? 'success' : 'retry', {
           attempt: attemptCount,
           property,
-          target_value: targetValue,
+          target_value: normalizedTargetValue,
           actual_state: observedState,
           reason: verificationResult.verification?.reason ?? 'gesture adjustment did not converge yet'
         })
@@ -1325,8 +2104,8 @@ export class ToolsInteract {
             uiFingerprintBefore: fingerprintBefore,
             uiFingerprintAfter,
             details: {
-              target_value: targetValue,
-              tolerance: normalizedTolerance,
+              target_value: normalizedTargetValue,
+              tolerance: effectiveTolerance,
               property,
               attempts: attemptCount,
               adjustment_mode: lastAdjustmentMode,
@@ -1342,8 +2121,8 @@ export class ToolsInteract {
             ...base,
             target_state: {
               property,
-              target_value: targetValue,
-              tolerance: normalizedTolerance
+              target_value: normalizedTargetValue,
+              tolerance: effectiveTolerance
             },
             actual_state: observedState,
             within_tolerance: true,
@@ -1361,7 +2140,7 @@ export class ToolsInteract {
         recordTraceStep('verify', 'success', {
           attempt: attemptCount,
           property,
-          target_value: targetValue,
+          target_value: normalizedTargetValue,
           actual_state: observedState,
           reason: verification?.reason ?? 'control converged to target value'
         })
@@ -1376,8 +2155,8 @@ export class ToolsInteract {
           uiFingerprintBefore: fingerprintBefore,
           uiFingerprintAfter,
           details: {
-            target_value: targetValue,
-            tolerance: normalizedTolerance,
+            target_value: normalizedTargetValue,
+            tolerance: effectiveTolerance,
             property,
             attempts: attemptCount,
             adjustment_mode: lastAdjustmentMode,
@@ -1393,8 +2172,8 @@ export class ToolsInteract {
           ...base,
           target_state: {
             property,
-            target_value: targetValue,
-            tolerance: normalizedTolerance
+            target_value: normalizedTargetValue,
+            tolerance: effectiveTolerance
           },
           actual_state: observedState,
           within_tolerance: true,
@@ -1404,23 +2183,25 @@ export class ToolsInteract {
         }
       }
 
-      cachedResolvedMatch = {
-        el: {
-          ...currentEl,
-          state: {
-            ...(currentEl.state ?? null),
-            ...(observedState ? {
-              [observedState.property]: observedState.value,
-              raw_value: observedState.raw_value ?? observedState.value
-            } : {})
-          }
-        },
-        idx: resolved.match.idx
-      }
+      cachedResolvedMatch = inferredSliderState
+        ? null
+        : {
+          el: {
+            ...currentEl,
+            state: {
+              ...(currentEl.state ?? null),
+              ...(observedState ? {
+                [observedState.property]: observedState.value,
+                raw_value: observedState.raw_value ?? observedState.value
+              } : {})
+            }
+          },
+          idx: resolved.match.idx
+        }
     }
 
     const uiFingerprintAfter = await ToolsInteract._captureFingerprint(resolvedPlatform, resolvedDeviceId)
-    return buildFailure('TIMEOUT', 'control did not converge within the allotted attempts', resolvedTarget, currentDevice, lastObservedState, attemptCount, lastAdjustmentMode, true, uiFingerprintAfter)
+    return buildFailure('CONTROL_CONVERGENCE_FAILED', 'control did not converge within the allotted attempts', resolvedTarget, currentDevice, lastObservedState, attemptCount, lastAdjustmentMode, true, uiFingerprintAfter)
   }
 
   static async swipeHandler({ platform = 'android', x1, y1, x2, y2, duration, deviceId }: { platform?: 'android' | 'ios', x1: number, y1: number, x2: number, y2: number, duration: number, deviceId?: string }) {
@@ -2021,33 +2802,79 @@ export class ToolsInteract {
     deviceId,
     timeout_ms = 60000,
     stability_window_ms = 300,
-    expected_change
+    expected_change,
+    scope = 'screen',
+    target = null
   }: {
     platform?: 'android' | 'ios',
     deviceId?: string,
     timeout_ms?: number,
     stability_window_ms?: number,
-    expected_change?: 'hierarchy_diff' | 'text_change' | 'state_change'
+    expected_change?: 'hierarchy_diff' | 'text_change' | 'state_change',
+    scope?: 'screen' | 'subtree',
+    target?: string | null
   }): Promise<WaitForUIChangeResponse> {
     const start = Date.now()
     const pollIntervalMs = 300
     const stabilityWindow = Math.max(0, typeof stability_window_ms === 'number' ? stability_window_ms : 300)
     let baseline: UiChangeSignatureSet | null = null
+    let baselineScope: UiChangeScopeResult | null = null
     let lastObservedRevision: number | null = null
     let lastLoadingState: any = null
+    let lastSnapshotFreshnessMs: number | null = null
     let candidateSignatures: UiChangeSignatureSet | null = null
     let candidateObservedChange: 'hierarchy_diff' | 'text_change' | 'state_change' | null = null
     let candidateSinceMs: number | null = null
+    let lastChangeSummary: ReturnType<typeof ToolsInteract._summarizeUiChangeDelta> | null = null
+    let lastScopeResolution: UiChangeScopeResolution = {
+      scope: scope === 'subtree' ? 'subtree' : 'screen',
+      target: target && typeof target === 'string' ? target : null,
+      resolved: scope !== 'subtree',
+      resolvedIndex: null,
+      resolvedStableId: null,
+      reason: scope === 'subtree' ? 'target not resolved yet' : 'screen scope'
+    }
 
     while (Date.now() - start < timeout_ms) {
       try {
         const tree = await ToolsObserve.getUITreeHandler({ platform, deviceId }) as any
-        const signatures = ToolsInteract._buildUiChangeSignatures(tree)
+        const scopedTree = ToolsInteract._resolveUiChangeScope(tree, scope, target)
+        if (scopedTree.error) {
+          lastScopeResolution = scopedTree.resolution
+          return {
+            success: false,
+            observed_change: null,
+            snapshot_revision: typeof tree?.snapshot_revision === 'number' ? tree.snapshot_revision : lastObservedRevision ?? undefined,
+            snapshot_freshness_ms: typeof tree?.captured_at_ms === 'number' ? Math.max(0, Date.now() - tree.captured_at_ms) : lastSnapshotFreshnessMs ?? null,
+            timeout: true,
+            elapsed_ms: Date.now() - start,
+            expected_change,
+            loading_state: tree?.loading_state ?? lastLoadingState ?? null,
+            scope: scopedTree.resolution.scope,
+            target: scopedTree.resolution.target,
+            stability_state: 'transient',
+            change_summary: lastChangeSummary,
+            reason: scopedTree.error.message,
+            error: scopedTree.error
+          }
+        }
+
+        const scopedElements = scopedTree.elements
+        const scopedSignatureTree = {
+          ...tree,
+          elements: scopedElements
+        }
+        const signatures = ToolsInteract._buildUiChangeSignatures(scopedSignatureTree)
         lastObservedRevision = typeof tree?.snapshot_revision === 'number' ? tree.snapshot_revision : lastObservedRevision
         lastLoadingState = tree?.loading_state ?? lastLoadingState
+        lastSnapshotFreshnessMs = typeof tree?.captured_at_ms === 'number' ? Math.max(0, Date.now() - tree.captured_at_ms) : lastSnapshotFreshnessMs
+        lastChangeSummary = baseline ? ToolsInteract._summarizeUiChangeDelta((baselineScope?.elements ?? []), scopedElements) : lastChangeSummary
+        lastScopeResolution = scopedTree.resolution
+        baselineScope = baselineScope ?? scopedTree
 
         if (!baseline) {
           baseline = signatures
+          baselineScope = scopedTree
         } else {
           const observedChange = ToolsInteract._matchesUiChange(expected_change, baseline, signatures)
           if (observedChange) {
@@ -2059,20 +2886,25 @@ export class ToolsInteract {
 
             const stableForMs = candidateSinceMs === null ? 0 : Date.now() - candidateSinceMs
             if (stabilityWindow === 0 || stableForMs >= stabilityWindow) {
-              return {
-                success: true,
-                observed_change: candidateObservedChange ?? observedChange,
-                snapshot_revision: lastObservedRevision ?? undefined,
-                timeout: false,
-                elapsed_ms: Date.now() - start,
-                expected_change,
-                loading_state: lastLoadingState ?? null,
-                reason: 'UI change observed'
+                return {
+                  success: true,
+                  observed_change: candidateObservedChange ?? observedChange,
+                  snapshot_revision: lastObservedRevision ?? undefined,
+                  snapshot_freshness_ms: lastSnapshotFreshnessMs ?? null,
+                  timeout: false,
+                  elapsed_ms: Date.now() - start,
+                  expected_change,
+                  loading_state: lastLoadingState ?? null,
+                  scope: lastScopeResolution.scope,
+                  target: lastScopeResolution.target,
+                  stability_state: 'stable',
+                  change_summary: lastChangeSummary,
+                  reason: 'UI change observed'
+                }
               }
-            }
-          } else {
-            candidateSignatures = null
-            candidateObservedChange = null
+            } else {
+              candidateSignatures = null
+              candidateObservedChange = null
             candidateSinceMs = null
           }
         }
@@ -2087,10 +2919,15 @@ export class ToolsInteract {
       success: false,
       observed_change: null,
       snapshot_revision: lastObservedRevision ?? undefined,
+      snapshot_freshness_ms: lastSnapshotFreshnessMs ?? null,
       timeout: true,
       elapsed_ms: Date.now() - start,
       expected_change,
       loading_state: lastLoadingState ?? null,
+      scope: lastScopeResolution.scope,
+      target: lastScopeResolution.target,
+      stability_state: 'transient',
+      change_summary: lastChangeSummary,
       reason: 'timeout'
     }
   }