mobile-debug-mcp 0.34.0 → 0.35.0

package/src/interact/targeting/target-scope.ts

@@ -0,0 +1,121 @@
+import type { UiElement, UiChangeScopeResult, ResolvedUiElementContext } from '../model.js'
+import { _normalize, _computeElementId } from './element-helpers.js'
+import { _collectSubtreeIndices } from '../waits/ui-change-helpers.js'
+
+export interface ScopeTree { elements?: UiElement[]; device?: { platform?: string; id?: string } }
+type StoreReader = { get(id: string): ResolvedUiElementContext | undefined }
+type ScopedMatch = { index: number; stableId: string | null; reason: string }
+
+export function findScopedElement(tree: ScopeTree | null | undefined, targetElementId: string, store: StoreReader): { 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 = _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: ScopeTree | null | undefined,
+    scope: 'screen' | 'subtree' | undefined,
+    target: string | null | undefined,
+    find: (tree: ScopeTree | null | undefined, id: string) => ScopedMatch | null
+  ): 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 = 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 is UiElement => !!element)
+
+    return {
+      elements: scopedElements,
+      resolution: {
+        scope: 'subtree',
+        target: requestedTarget,
+        resolved: true,
+        resolvedIndex: resolved.index,
+        resolvedStableId: resolved.stableId,
+        reason: resolved.reason
+      }
+    }
+  }
+
+function findStableElement(elements: UiElement[], normalizedTarget: string, reason: string): ScopedMatch | null {
+  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
+}

package/src/interact/waits/legacy-log-wait.ts

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

package/src/interact/waits/legacy-wait-observations.ts

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

package/src/interact/waits/legacy-wait-state.ts

@@ -0,0 +1,48 @@
+import { systemClock, type Clock } from '../../runtime/clock.js'
+import type { FindElementResponse, FindElementElement } from '../../types.js'
+import type { FindInput } from '../targeting/find-element.js'
+import type { DeviceTarget } from '../observation.js'
+export interface LegacyWaitInput extends DeviceTarget {
+  type?: 'ui' | 'log' | 'screen' | 'idle'; query?: string; timeoutMs?: number; pollIntervalMs?: number
+  includeSnapshotOnFailure?: boolean; match?: 'present' | 'absent'; stability_ms?: number; observationDelayMs?: number
+}
+export interface LegacyWaitDependencies {
+  clock?: Clock
+  fingerprint(target: DeviceTarget): Promise<{ fingerprint: string | null } | null>
+  logs(target: DeviceTarget & { lines: number }): Promise<{ logs?: unknown[] } | null>
+  stream(target: DeviceTarget & { sessionId: string; limit: number }): Promise<{ entries?: unknown[] } | null>
+  find(input: FindInput): Promise<FindElementResponse>
+  snapshot(input: DeviceTarget & { reason: string; includeLogs: boolean }): Promise<unknown>
+}
+export function createLegacyWait({ type = 'ui', query, timeoutMs = 30000, pollIntervalMs = 300,
+  includeSnapshotOnFailure = true, match = 'present', stability_ms = 700, observationDelayMs = 0, platform, deviceId }: LegacyWaitInput, clock: Clock = systemClock) {
+  const start = clock.now()
+  return { clock, type, query: query == null ? '' : String(query), start, deadline: start + (timeoutMs || 0),
+    interval: Math.max(250, Math.min(pollIntervalMs || 300, 500)), includeSnapshotOnFailure, match, stability_ms, observationDelayMs,
+    target: { platform, deviceId }, initial: null as string | null, baseline: null as unknown,
+    lastChange: 0, previous: null as string | null, polls: 0, matched: null as number | null,
+    observed: null as boolean | null, duration: 0 }
+}
+export type LegacyWait = ReturnType<typeof createLegacyWait>
+export function logMessages(entries: unknown[]): unknown[] {
+  if (!Array.isArray(entries)) return []
+  return entries.map(entry => {
+    if (typeof entry === 'string') return entry
+    if (entry && typeof entry === 'object') {
+      const fields = entry as { message?: unknown; msg?: unknown }
+      if (fields.message || fields.msg) return fields.message || fields.msg
+    }
+    try { return JSON.stringify(entry) } catch { return String(entry) }
+  })
+}
+interface LegacyExtras {
+  matchedElement?: FindElementElement | null
+  matchedLog?: { message: unknown; raw?: unknown }
+  newFingerprint?: string | null
+}
+export function legacySuccess(s: LegacyWait, type: string, matchSource: string, stable: number, extras: LegacyExtras = {}, condition = 'present') {
+  const now = s.clock.now()
+  return { success: true, condition, query: s.query, poll_count: s.polls, duration_ms: now - s.start,
+    stable_duration_ms: stable, ...extras, matchSource, timestamp: now, type, observed_state: s.observed ?? null }
+}
+export const legacySleep = (ms: number, clock: Clock = systemClock) => clock.sleep(ms)

package/src/interact/waits/legacy-wait.ts

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

package/src/interact/waits/screen-wait.ts

@@ -0,0 +1,37 @@
+import { systemClock, type Clock } from '../../runtime/clock.js'
+import { checkDebuggerGuard } from '../../debugger/guard.js'
+import type { ScreenAccess } from '../assertions/screen-assertion.js'
+import type { DeviceTarget } from '../observation.js'
+export interface ScreenWaitInput extends DeviceTarget { previousFingerprint: string; timeoutMs?: number; pollIntervalMs?: number }
+interface ScreenState { clock: Clock; start: number; fingerprint: string | null; activity: string | null }
+async function sample(s: ScreenState, input: ScreenWaitInput, interval: number, deps: Pick<ScreenAccess, 'fingerprint'> & { clock?: Clock }) {
+  const response = await deps.fingerprint({ platform: input.platform, deviceId: input.deviceId })
+  const fingerprint = response?.fingerprint ?? null
+  s.activity = response?.activity ?? s.activity
+  if (fingerprint == null) { s.fingerprint = null; await s.clock.sleep(interval); return 'continue' as const }
+  s.fingerprint = fingerprint
+  if (fingerprint === input.previousFingerprint) return null
+  await s.clock.sleep(interval)
+  try {
+    const confirm = await deps.fingerprint({ platform: input.platform, deviceId: input.deviceId })
+    const confirmed = confirm?.fingerprint ?? null
+    s.activity = confirm?.activity ?? s.activity
+    if (confirmed === fingerprint) return { success: true, previousFingerprint: input.previousFingerprint, newFingerprint: fingerprint,
+      elapsedMs: s.clock.now() - s.start, observed_screen: { fingerprint, activity: s.activity } }
+    s.fingerprint = confirmed
+  } catch (error) { checkDebuggerGuard(); console.error('Error confirming fingerprint:', error) }
+  return 'continue' as const
+}
+export async function waitForScreenChange({ platform, previousFingerprint, timeoutMs = 5000, pollIntervalMs = 300, deviceId }: ScreenWaitInput, deps: Pick<ScreenAccess, 'fingerprint'> & { clock?: Clock }) {
+  const state: ScreenState = { clock: deps.clock ?? systemClock, start: (deps.clock ?? systemClock).now(), fingerprint: null, activity: null }
+  while (state.clock.now() - state.start < timeoutMs) {
+    try {
+      const result = await sample(state, { platform, previousFingerprint, deviceId }, pollIntervalMs, deps)
+      if (result === 'continue') continue
+      if (result) return result
+    } catch (error) { checkDebuggerGuard(); console.error('Error getting screen fingerprint:', error) }
+    await state.clock.sleep(pollIntervalMs)
+  }
+  return { success: false, reason: 'timeout', previousFingerprint, lastFingerprint: state.fingerprint,
+    elapsedMs: state.clock.now() - state.start, observed_screen: { fingerprint: state.fingerprint, activity: state.activity } }
+}

package/src/interact/waits/ui-change-helpers.ts

@@ -0,0 +1,184 @@
+import { computeSnapshotSignature } from '../../observe/snapshot-metadata.js'
+import type { UIElementState } from '../../types.js'
+import type { UiElement, UiChangeSignatureSet } from '../model.js'
+const _uiChangeKinds: Array<'hierarchy_diff' | 'text_change' | 'state_change'> = ['hierarchy_diff', 'text_change', 'state_change']
+import { _normalize, _normalizeBounds, _hash, _resolveParentIndex } from '../targeting/element-helpers.js'
+
+export function _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 = childIndices(elements, element, index)
+
+      for (const childIndex of directChildren) {
+        if (!visited.has(childIndex)) stack.push(childIndex)
+      }
+    }
+
+    return result.sort((left, right) => left - right)
+  }
+
+export function _changeIdentityForElement(el: UiElement, index: number): string {
+    const stableId = _normalize(el.stable_id)
+    if (stableId) return `stable:${stableId}`
+
+    return `fallback:${_hash({
+      text: _normalize(el.text ?? el.label ?? el.value ?? ''),
+      contentDescription: _normalize(el.contentDescription ?? el.contentDesc ?? el.accessibilityLabel ?? ''),
+      resourceId: _normalize(el.resourceId ?? el.resourceID ?? el.id ?? ''),
+      type: _normalize(el.type ?? el.class ?? ''),
+      bounds: _normalizeBounds(el.bounds) ?? [0, 0, 0, 0],
+      index
+    })}`
+  }
+
+export function _summarizeUiChangeDelta(initialElements: 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 = _changeIdentityForElement(element, i)
+        map.set(key, _hash({
+          text: _normalize(element.text ?? element.label ?? element.value ?? ''),
+          contentDescription: _normalize(element.contentDescription ?? element.contentDesc ?? element.accessibilityLabel ?? ''),
+          resourceId: _normalize(element.resourceId ?? element.resourceID ?? element.id ?? ''),
+          type: _normalize(element.type ?? element.class ?? ''),
+          bounds: _normalizeBounds(element.bounds) ?? [0, 0, 0, 0],
+          state: element.state ?? null,
+          visible: !!element.visible,
+          enabled: !!element.enabled,
+          clickable: !!element.clickable
+        }))
+      }
+      return map
+    }
+
+    const initialMap = buildMap(initialElements)
+    const currentMap = buildMap(currentElements)
+    let added = 0
+    let removed = 0
+    let mutated = 0
+
+    for (const [key, value] of currentMap.entries()) {
+      if (!initialMap.has(key)) {
+        added++
+      } else if (initialMap.get(key) !== value) {
+        mutated++
+      }
+    }
+
+    for (const key of initialMap.keys()) {
+      if (!currentMap.has(key)) removed++
+    }
+
+    return {
+      total_elements: currentElements.length,
+      added_elements: added,
+      removed_elements: removed,
+      mutated_elements: mutated
+    }
+  }
+
+export function _buildUiChangeSignatures(tree: Parameters<typeof computeSnapshotSignature>[0]): UiChangeSignatureSet {
+    const elements = Array.isArray(tree?.elements) ? tree.elements as UiElement[] : []
+    const textPayload: Array<{ text: string, contentDescription: string, resourceId: string }> = []
+    const statePayload: Array<{
+      checked: boolean | null
+      selected: boolean | string | { id: string; label?: string } | null
+      focused: boolean | null
+      expanded: boolean | null
+      enabled: boolean | null
+      text_value: string | null
+      value: number | string | null
+      raw_value: number | string | null
+      value_range: UIElementState['value_range']
+    }> = []
+
+    for (const el of elements) {
+      textPayload.push(textSignature(el))
+      statePayload.push(stateSignature(el))
+    }
+
+    return {
+      hierarchy: computeSnapshotSignature(tree),
+      text: _hash({
+        screen: _normalize(tree?.screen),
+        elements: textPayload
+      }),
+      state: _hash({
+        screen: _normalize(tree?.screen),
+        elements: statePayload
+      })
+    }
+  }
+
+export function _matchesUiChange(expected: 'hierarchy_diff' | 'text_change' | 'state_change' | undefined, initial: UiChangeSignatureSet, current: UiChangeSignatureSet): 'hierarchy_diff' | 'text_change' | 'state_change' | null {
+    const candidates = expected ? [expected] : _uiChangeKinds
+
+    for (const changeKind of candidates) {
+      if (changeKind === 'hierarchy_diff' && initial.hierarchy !== current.hierarchy) return changeKind
+      if (changeKind === 'text_change' && initial.text !== current.text) return changeKind
+      if (changeKind === 'state_change' && initial.state !== current.state) return changeKind
+    }
+
+    return null
+  }
+
+export function _uiChangeSignaturesEqual(left: UiChangeSignatureSet, right: UiChangeSignatureSet): boolean {
+    return left.hierarchy === right.hierarchy && left.text === right.text && left.state === right.state
+  }
+
+function childIndices(elements: UiElement[], element: UiElement, index: number) {
+  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 (_resolveParentIndex(elements, elements[i]?.parentId) === index) {
+      directChildren.add(i)
+    }
+  }
+
+
+  return directChildren
+}
+
+function textSignature(el: UiElement | null) {
+  return {
+    text: _normalize(el?.text ?? el?.label ?? el?.value ?? ''),
+    contentDescription: _normalize(el?.contentDescription ?? el?.contentDesc ?? el?.accessibilityLabel ?? ''),
+    resourceId: _normalize(el?.resourceId ?? el?.resourceID ?? el?.id ?? '')
+  }
+}
+function stateSignature(el: UiElement | null) {
+  const state = el?.state ?? {}
+  return {
+    checked: state.checked ?? null,
+    selected: state.selected ?? null,
+    focused: state.focused ?? null,
+    expanded: state.expanded ?? null,
+    enabled: state.enabled ?? null,
+    text_value: state.text_value ?? null,
+    value: state.value ?? null,
+    raw_value: state.raw_value ?? null,
+    value_range: state.value_range ?? null
+  }
+}

package/src/interact/waits/ui-change-state.ts

@@ -0,0 +1,26 @@
+import { systemClock, type Clock } from '../../runtime/clock.js'
+import type { LoadingState, WaitForUIChangeResponse } from '../../types.js'
+import type { DeviceTarget } from '../observation.js'
+import type { UiChangeSignatureSet, UiChangeScopeResult, UiChangeScopeResolution } from '../model.js'
+import { _summarizeUiChangeDelta } from './ui-change-helpers.js'
+import { currentReadinessWait } from '../../observe/readiness.js'
+export interface ChangeInput extends DeviceTarget {
+  timeout_ms?: number; stability_window_ms?: number; expected_change?: 'hierarchy_diff' | 'text_change' | 'state_change'; scope?: 'screen' | 'subtree'; target?: string | null
+}
+export function createChangeWait({ platform, deviceId, timeout_ms = 60000, stability_window_ms = 300, expected_change, scope = 'screen', target = null }: ChangeInput, clock: Clock = systemClock) {
+  const tracker = currentReadinessWait(), start = clock.now()
+  return { clock, input: { platform, deviceId, timeout_ms, expected_change, scope, target }, tracker, start,
+    stability: Math.max(0, typeof stability_window_ms === 'number' ? stability_window_ms : 300), baseline: null as UiChangeSignatureSet | null,
+    baselineScope: null as UiChangeScopeResult | null, revision: null as number | null, loading: null as LoadingState | null,
+    age: null as number | null, candidate: null as UiChangeSignatureSet | null, change: null as WaitForUIChangeResponse['observed_change'],
+    since: null as number | null, summary: null as ReturnType<typeof _summarizeUiChangeDelta> | null,
+    scope: { scope: scope === 'subtree' ? 'subtree' : 'screen', target: target && typeof target === 'string' ? target : null,
+      resolved: scope !== 'subtree', resolvedIndex: null, resolvedStableId: null, reason: scope === 'subtree' ? 'target not resolved yet' : 'screen scope' } as UiChangeScopeResolution }
+}
+export type ChangeWait = ReturnType<typeof createChangeWait>
+export function changeResult(s: ChangeWait, success: boolean, reason: string): WaitForUIChangeResponse {
+  return { success, observed_change: success ? s.change : null, snapshot_revision: s.revision ?? undefined,
+    snapshot_freshness_ms: s.age ?? null, timeout: !success, elapsed_ms: s.clock.now() - s.start,
+    expected_change: s.input.expected_change, loading_state: s.loading ?? null, scope: s.scope.scope, target: s.scope.target,
+    stability_state: success ? 'stable' : 'transient', change_summary: s.summary, reason }
+}

package/src/interact/waits/ui-change-wait.ts

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

package/src/interact/waits/ui-wait-condition.ts

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