mobile-debug-mcp 0.34.0 → 0.35.0

package/src/interact/adjustment/control-geometry.ts

@@ -0,0 +1,120 @@
+import type { UiElement } from '../model.js'
+import { _normalize } from '../targeting/element-helpers.js'
+
+export function _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
+    const width = Math.max(1, right - left)
+    const height = Math.max(1, bottom - top)
+    const insetX = Math.max(8, Math.floor(width * 0.08))
+    const insetY = Math.max(8, Math.floor(height * 0.08))
+    if (axis === 'vertical') {
+      const usableHeight = Math.max(1, height - (insetY * 2))
+      return {
+        x: Math.floor((left + right) / 2),
+        y: Math.floor(bottom - insetY - (usableHeight * clampedRatio))
+      }
+    }
+    const usableWidth = Math.max(1, width - (insetX * 2))
+    return {
+      x: Math.floor(left + insetX + (usableWidth * clampedRatio)),
+      y: Math.floor((top + bottom) / 2)
+    }
+  }
+
+export function _buildConservativeControlPoint(
+    bounds: [number, number, number, number],
+    targetValue: number,
+    currentValue: number | null,
+    min: number,
+    max: number,
+    axis: 'horizontal' | 'vertical'
+  ) {
+    const range = Math.max(1, max - min)
+    const targetRatio = (targetValue - min) / range
+    const stepRatio = 1 / range
+    const centerBias = stepRatio / 2
+    const direction = currentValue === null ? 0 : Math.sign(targetValue - currentValue)
+    const controlLengthPx = axis === 'vertical' ? Math.max(1, bounds[3] - bounds[1]) : Math.max(1, bounds[2] - bounds[0])
+    const edgeWindow = Math.max(3, Math.floor(range * 0.1))
+    const isNearLowEdge = targetValue - min <= edgeWindow
+    const isNearHighEdge = max - targetValue <= edgeWindow
+    const directionBias = direction > 0
+      ? -stepRatio * 0.15
+      : direction < 0
+        ? stepRatio * 0.65
+        : 0
+    const pixelBasedMargin = Math.min(0.03, Math.max(0.005, 2 / controlLengthPx))
+    const endpointMargin = Math.max(stepRatio * 0.5, pixelBasedMargin)
+    const edgeBias = isNearLowEdge
+      ? endpointMargin
+      : isNearHighEdge
+        ? Math.max(stepRatio * 0.4, endpointMargin * 0.75)
+        : 0
+    const safeRatio = Math.min(
+      1 - (endpointMargin * 0.25),
+      Math.max(endpointMargin, targetRatio + centerBias + directionBias + edgeBias)
+    )
+    return _buildControlPoint(bounds, safeRatio, axis)
+  }
+
+export function _buildAdjustmentProbePoints(
+    bounds: [number, number, number, number],
+    targetValue: number,
+    currentValue: number | null,
+    min: number,
+    max: number,
+    axis: 'horizontal' | 'vertical'
+  ) {
+    const targetPoint = _buildConservativeControlPoint(bounds, targetValue, currentValue, min, max, axis)
+    const currentPoint = currentValue !== null
+      ? _buildControlPoint(bounds, (currentValue - min) / (max - min), axis)
+      : _buildControlPoint(bounds, 0.5, axis)
+
+    const [left, top, right, bottom] = bounds
+    const width = Math.max(1, right - left)
+    const height = Math.max(1, bottom - top)
+    const crossAxisBumps = axis === 'horizontal'
+      ? [Math.max(24, Math.floor(height * 0.75)), Math.max(40, Math.floor(height * 1.5))]
+      : [Math.max(24, Math.floor(width * 0.75)), Math.max(40, Math.floor(width * 1.5))]
+
+    const clampPoint = (point: { x: number, y: number }) => ({
+      x: axis === 'horizontal'
+        ? Math.max(left, Math.min(right, point.x))
+        : Math.max(left, Math.min(right + Math.max(width, height), point.x)),
+      y: axis === 'vertical'
+        ? Math.max(top, Math.min(bottom, point.y))
+        : Math.max(top, Math.min(bottom + Math.max(height, width), point.y))
+    })
+
+    const probes = [targetPoint, currentPoint]
+    for (const bump of crossAxisBumps) {
+      if (axis === 'horizontal') {
+        probes.push(
+          { x: targetPoint.x, y: bottom + bump },
+          { x: currentPoint.x, y: bottom + bump }
+        )
+      } else {
+        probes.push(
+          { x: right + bump, y: targetPoint.y },
+          { x: right + bump, y: currentPoint.y }
+        )
+      }
+    }
+
+    return Array.from(
+      new Map(
+        probes
+          .map(clampPoint)
+          .map((point) => [`${point.x}:${point.y}`, point] as const)
+      ).values()
+    )
+  }
+
+export function _controlAxis(el: UiElement, bounds: [number, number, number, number]): 'horizontal' | 'vertical' {
+    const type = _normalize(el.type ?? el.class ?? '')
+    const role = _normalize(el.role ?? '')
+    if (/vertical/.test(type) || /vertical/.test(role)) return 'vertical'
+    if (/horizontal/.test(type) || /horizontal/.test(role)) return 'horizontal'
+    return (bounds[3] - bounds[1]) > (bounds[2] - bounds[0]) ? 'vertical' : 'horizontal'
+  }

package/src/interact/adjustment/control-values.ts

@@ -0,0 +1,141 @@
+import type { UIElementState } from '../../types.js'
+import type { UiElement } from '../model.js'
+import { _normalize } from '../targeting/element-helpers.js'
+
+export function _readNumericControlValue(el: UiElement | null, property: string): number | null {
+    if (!el?.state) return null
+    const stateValue = el.state[property as keyof UIElementState]
+    if (typeof stateValue === 'number' && Number.isFinite(stateValue)) return stateValue
+    const parsedStateValue = _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 _parseNumericControlValue(fallback)
+    }
+    return null
+  }
+
+export function _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
+  }
+
+export function _readNumericControlRange(el: UiElement | null): { min: number; max: number } | null {
+    const range = el?.state?.value_range
+    const min = typeof range?.min === 'number' ? range.min : null
+    const max = typeof range?.max === 'number' ? range.max : null
+    if (min !== null && max !== null && Number.isFinite(min) && Number.isFinite(max) && max > min) {
+      return { min, max }
+    }
+
+    return rangeFromFraction(el?.state?.value ?? el?.state?.raw_value)
+  }
+
+function rangeFromFraction(value: unknown): { min: number; max: number } | null {
+    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
+  }
+
+export function _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
+  }
+
+export function _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 = _decimalPrecisionForStep(step)
+    return Number(bounded.toFixed(precision))
+  }
+
+export function _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))
+  }
+
+export function _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))
+  }
+
+export function _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) => _normalize(value)).filter(Boolean))
+  }
+
+export function _hasDirectAdjustmentAction(el: UiElement | null): boolean {
+    const actions = _runtimeActionSet(el)
+    return [
+      'action_set_progress',
+      'set_progress',
+      'setprogress',
+      'semanticsactions.setprogress',
+      'set_value',
+      'setvalue',
+      'direct_set_value'
+    ].some((action) => actions.has(action))
+  }
+
+export function _adjustmentDirections(el: UiElement | null): { increment: boolean; decrement: boolean } {
+    const actions = _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))
+    }
+  }
+
+export function _textFromElement(el: UiElement | null): string {
+    return String(el?.text ?? el?.contentDescription ?? el?.contentDesc ?? el?.accessibilityLabel ?? el?.value ?? '').trim()
+  }
+
+export function _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
+  }

package/src/interact/adjustment/slider-labels.ts

@@ -0,0 +1,84 @@
+import type { UiElement, InferredLabeledSliderState } from '../model.js'
+import { _normalize, _normalizeBounds } from '../targeting/element-helpers.js'
+import { _textFromElement, _parseLeadingNumber } from './control-values.js'
+
+export function _inferLabeledSliderState(elements: UiElement[], track: UiElement | null): InferredLabeledSliderState | null {
+    const trackBounds = _normalizeBounds(track?.bounds)
+    if (!track || !trackBounds) return null
+    const type = _normalize(track.type ?? track.class ?? '')
+    const role = _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 = _normalizeBounds(el.bounds)
+        const text = _textFromElement(el)
+        const value = _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'
+    }
+  }

package/src/interact/assertions/screen-assertion.ts

@@ -0,0 +1,39 @@
+import type { ExpectScreenResponse } from '../../types.js'
+import type { DeviceTarget } from '../observation.js'
+import { buildObservationTrace } from '../interaction-trace.js'
+export interface ScreenExpectation extends DeviceTarget { fingerprint?: string; screen?: string }
+export interface ScreenAccess {
+  fingerprint(target: DeviceTarget): Promise<{ fingerprint: string | null; activity?: string | null } | null>
+  current(target: { deviceId?: string }): Promise<{ activity?: string; shortActivity?: string } | null>
+}
+function compareScreen(input: ScreenExpectation, observed: { fingerprint: string | null; screen: string | null }, label: string | null) {
+  const { fingerprint, screen } = input
+  if (fingerprint) {
+    const success = observed.fingerprint === fingerprint
+    return { success, basis: 'fingerprint' as const, reason: success ? `observed fingerprint matches expected fingerprint ${fingerprint}` : `expected fingerprint ${fingerprint} but observed ${observed.fingerprint ?? 'null'}` }
+  }
+  if (screen) {
+    const candidates = new Set<string>()
+    if (observed.screen) candidates.add(observed.screen)
+    if (label) candidates.add(label)
+    const success = candidates.has(screen)
+    return { success, basis: 'screen' as const, reason: success ? `observed screen matches expected screen ${screen}` : `expected screen ${screen} but observed ${label ?? observed.screen ?? 'null'}` }
+  }
+  return { success: false, basis: 'none' as const, reason: 'No fingerprint or screen expectation provided' }
+}
+export async function expectScreen(input: ScreenExpectation, deps: ScreenAccess): Promise<ExpectScreenResponse> {
+  const observed = await deps.fingerprint({ platform: input.platform, deviceId: input.deviceId })
+  const screen = { fingerprint: observed?.fingerprint ?? null, screen: observed?.activity ?? null }
+  let label = screen.screen
+  if (!input.fingerprint && input.screen && input.platform !== 'ios') {
+    try { const current = await deps.current({ deviceId: input.deviceId }); label = current?.shortActivity || current?.activity || label }
+    catch { /* Keep the fingerprint-derived activity if current-screen lookup is unavailable. */ }
+  }
+  const comparison = compareScreen(input, screen, label)
+  const expected = { fingerprint: input.fingerprint ?? null, screen: input.screen ?? null }
+  const observedScreen = { fingerprint: screen.fingerprint, screen: label }
+  return { success: comparison.success, observed_screen: observedScreen, expected_screen: expected,
+    confidence: comparison.success ? 1 : 0, comparison: { basis: comparison.basis, matched: comparison.success, reason: comparison.reason },
+    trace: buildObservationTrace({ actionType: 'expect_screen', stage: 'verify', success: comparison.success, attempts: 1,
+      metadata: { expected_screen: expected, observed_screen: observedScreen, comparison: { basis: comparison.basis, matched: comparison.success } } }) }
+}

package/src/interact/assertions/state-assertion-context.ts

@@ -0,0 +1,48 @@
+import { systemClock, type Clock } from '../../runtime/clock.js'
+import type { ActionTargetResolved, ExpectStateResponse, TraceStep, UIElementState } from '../../types.js'
+import type { DeviceTarget, ObserveUI } from '../observation.js'
+import type { UiSelector } from '../../contracts/selector.js'
+import type { AdjustmentDependencies } from '../adjustment/adjustment-context.js'
+import { createTraceStep, nextActionId } from '../../runtime/action-results.js'
+import type { StateComparison } from './state-comparison.js'
+export interface StateInput extends DeviceTarget {
+  selector?: UiSelector; element_id?: string; property: string; expected: ExpectStateResponse['expected_state']['expected']
+  stabilization_window_ms?: number; stable_observation_count?: number; snapshot_stale_threshold_ms?: number; poll_interval_ms?: number; exact_budget?: boolean
+}
+export type StateDependencies = Pick<AdjustmentDependencies, 'getHandle' | 'currentHandle' | 'target'> & { observe: ObserveUI; clock?: Clock }
+export function createStateAssertion({ selector, element_id, property, expected, platform, deviceId,
+  stabilization_window_ms = 1000, stable_observation_count = 2, snapshot_stale_threshold_ms = 500,
+  poll_interval_ms = 150, exact_budget = false }: StateInput, clock: Clock = systemClock) {
+  const start = clock.now()
+  return { clock, input: { selector, element_id, property, expected, platform, deviceId }, start,
+    deadline: start + (exact_budget ? stabilization_window_ms : Math.max(500, stabilization_window_ms)),
+    stableTarget: Math.max(1, Math.floor(stable_observation_count || 2)),
+    delay: exact_budget ? Math.max(50, Math.min(poll_interval_ms || 150, 1000)) : Math.max(100, Math.min(poll_interval_ms || 150, 200)),
+    stale: Math.max(300, Math.min(snapshot_stale_threshold_ms || 500, 800)), attempts: 0, stable: 0, reason: 'element not found',
+    failure: 'ELEMENT_NOT_FOUND' as 'ELEMENT_NOT_FOUND' | 'UNKNOWN', element: null as (ActionTargetResolved & { state?: UIElementState | null }) | null,
+    value: null as StateComparison['observedValue'], raw: null as StateComparison['rawValue'], id: element_id ?? null,
+    trace: [] as TraceStep[], sequence: 0, resolveRecorded: false }
+}
+export type StateAssertion = ReturnType<typeof createStateAssertion>
+export function recordState(s: StateAssertion, stage: TraceStep['stage'], result: TraceStep['result'], metadata: Record<string, unknown>) {
+  s.trace.push(createTraceStep({ stage, timestamp: s.clock.now(), result, attemptIndex: s.sequence++, metadata }))
+}
+export function stabilizeState(s: StateAssertion, result: 'success' | 'retry', age: number | null, reason: string) {
+  recordState(s, 'stabilize', result, { stabilization_attempts: s.attempts, stable_observation_count: s.stable, snapshot_freshness_ms: age, reason })
+}
+function trace(s: StateAssertion, outcome: 'success' | 'failure') {
+  return { action_id: nextActionId('expect_state', s.clock.now()), steps: s.trace, final_outcome: outcome, attempts: s.attempts }
+}
+export function stateSuccess(s: StateAssertion, comparison: StateComparison, age: number | null): ExpectStateResponse {
+  return { success: true, selector: s.input.selector, element_id: s.id,
+    expected_state: { property: s.input.property, expected: s.input.expected }, element: s.element,
+    observed_state: { property: s.input.property, value: comparison.observedValue, ...(comparison.rawValue !== null ? { raw_value: comparison.rawValue } : {}) },
+    reason: comparison.reason, stabilization_attempts: s.attempts, stabilization_window_ms: s.clock.now() - s.start,
+    stable_observation_count: s.stable, snapshot_freshness_ms: age ?? undefined, trace: trace(s, 'success') }
+}
+export function stateFailure(s: StateAssertion): ExpectStateResponse {
+  return { success: false, selector: s.input.selector, element_id: s.id,
+    expected_state: { property: s.input.property, expected: s.input.expected }, element: s.element,
+    observed_state: { property: s.input.property, value: s.value, ...(s.raw !== null ? { raw_value: s.raw } : {}) },
+    reason: s.reason, failure_code: s.failure, retryable: true, trace: trace(s, 'failure') }
+}

package/src/interact/assertions/state-assertion.ts

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

package/src/interact/assertions/state-comparison.ts

@@ -0,0 +1,168 @@
+import type { UIElementState, ExpectStateResponse } from '../../types.js';
+type Expected = ExpectStateResponse['expected_state']['expected'];
+type Observed = NonNullable<ExpectStateResponse['observed_state']>['value'];
+export interface StateComparison {
+  success: boolean;
+  reason: string;
+  rawValue: boolean | number | string | null;
+  observedValue: Observed;
+}
+interface ComparisonInput {
+  property: string;
+  expected: Expected;
+  actual: Observed;
+  observedState: UIElementState | null;
+}
+const compareBoolean = (value: unknown) => typeof value === 'boolean' ? value : null;
+const compareString = (value: unknown) => typeof value === 'string' ? value : null;
+const compareNumber = (value: unknown) => typeof value === 'number' && Number.isFinite(value) ? value : null;
+export function compareReadableState(property: string, expected: Expected, observedState: UIElementState | null): StateComparison {
+  const input = { property, expected, observedState, actual: observedState?.[property as keyof UIElementState] ?? null };
+  if (['checked', 'focused', 'expanded', 'enabled'].includes(property))
+    return compareBooleanState(input);
+  if (['value', 'raw_value'].includes(property))
+    return compareValueState(input);
+  if (property === 'selected')
+    return compareSelectedState(input);
+  if (property === 'text_value')
+    return compareTextState(input);
+  return compareOtherState(input);
+}
+function compareBooleanState({ property, expected, actual }: ComparisonInput): StateComparison {
+  let success = false;
+  let reason = '';
+  let rawValue: StateComparison['rawValue'] = null;
+  let observedValue: Observed = actual;
+  const expectedBool = compareBoolean(expected);
+  const actualBool = compareBoolean(actual);
+  if (expectedBool === null) {
+    reason = `expected ${property} must be boolean`;
+  }
+  else if (actualBool === null) {
+    reason = `${property} state unavailable`;
+  }
+  else {
+    rawValue = actualBool;
+    success = actualBool === expectedBool;
+    reason = success ? `${property} matches expected value` : `expected ${property}=${expectedBool} but observed ${actualBool}`;
+  }
+  observedValue = actualBool;
+  return { success, reason, rawValue, observedValue };
+}
+function compareValueState({ expected, actual }: ComparisonInput): StateComparison {
+  let success = false;
+  let reason = '';
+  let rawValue: StateComparison['rawValue'] = null;
+  let observedValue: Observed = actual;
+  const expectedNumber = compareNumber(expected);
+  const actualNumber = compareNumber(actual);
+  if (expectedNumber !== null && actualNumber !== null) {
+    success = actualNumber === expectedNumber;
+    rawValue = actualNumber;
+    observedValue = actualNumber;
+    reason = success ? 'value matches expected value' : `expected value=${expectedNumber} but observed ${actualNumber}`;
+    return { success, reason, rawValue, observedValue };
+  }
+  const expectedString = typeof expected === 'string' ? expected : null;
+  const actualString = compareString(actual);
+  if (expectedString !== null && actualString !== null) {
+    success = actualString === expectedString;
+    rawValue = actualString;
+    observedValue = actualString;
+    reason = success ? 'value matches expected value' : `expected value=${expectedString} but observed ${actualString}`;
+  }
+  else {
+    reason = 'value state unavailable';
+  }
+  return { success, reason, rawValue, observedValue };
+}
+function compareSelectedState({ expected, actual, observedState }: ComparisonInput): StateComparison {
+  let success = false;
+  let reason = '';
+  let rawValue: StateComparison['rawValue'] = null;
+  let observedValue: Observed = actual;
+  const expectedBool = typeof expected === 'boolean' ? expected : null;
+  const expectedString = typeof expected === 'string'
+    ? expected
+    : expected && typeof expected === 'object'
+      ? String((expected as {
+        id?: unknown;
+        label?: unknown;
+      }).id ?? (expected as {
+        id?: unknown;
+        label?: unknown;
+      }).label ?? '')
+      : null;
+  if (!observedState || observedState.selected === undefined || observedState.selected === null) {
+    reason = 'selected state unavailable';
+    return { success, reason, rawValue, observedValue };
+  }
+  if (expectedBool !== null) {
+    const actualBool = typeof observedState.selected === 'boolean' ? observedState.selected : null;
+    if (actualBool === null) {
+      reason = 'selected state is not boolean';
+      return { success, reason, rawValue, observedValue };
+    }
+    rawValue = actualBool;
+    observedValue = actualBool;
+    success = actualBool === expectedBool;
+    reason = success ? 'selected matches expected value' : `expected selected=${expectedBool} but observed ${actualBool}`;
+    return { success, reason, rawValue, observedValue };
+  }
+  const actualSelected = typeof observedState.selected === 'object' && observedState.selected !== null
+    ? String((observedState.selected as {
+      id?: unknown;
+      label?: unknown;
+    }).id ?? (observedState.selected as {
+      id?: unknown;
+      label?: unknown;
+    }).label ?? '')
+    : String(observedState.selected);
+  const actualString = actualSelected.trim();
+  if (!expectedString) {
+    reason = 'expected selected must be boolean, string, or object with id/label';
+    return { success, reason, rawValue, observedValue };
+  }
+  rawValue = actualString;
+  observedValue = actualString;
+  success = actualString === expectedString;
+  reason = success ? 'selected matches expected value' : `expected selected=${expectedString} but observed ${actualString}`;
+  return { success, reason, rawValue, observedValue };
+}
+function compareTextState({ expected, actual }: ComparisonInput): StateComparison {
+  let success = false;
+  let reason = '';
+  let rawValue: StateComparison['rawValue'] = null;
+  let observedValue: Observed = actual;
+  const expectedString = typeof expected === 'string' ? expected : null;
+  const actualString = compareString(actual);
+  if (!expectedString) {
+    reason = 'expected text_value must be string';
+  }
+  else if (!actualString) {
+    reason = 'text_value state unavailable';
+  }
+  else {
+    success = actualString === expectedString;
+    rawValue = actualString;
+    observedValue = actualString;
+    reason = success ? 'text_value matches expected value' : `expected text_value=${expectedString} but observed ${actualString}`;
+  }
+  return { success, reason, rawValue, observedValue };
+}
+function compareOtherState({ property, expected, actual }: ComparisonInput): StateComparison {
+  let success = false;
+  let reason = '';
+  let rawValue: StateComparison['rawValue'] = null;
+  let observedValue: Observed = actual;
+  if (actual !== null && actual !== undefined) {
+    success = actual === expected;
+    observedValue = actual;
+    rawValue = typeof actual === 'string' || typeof actual === 'number' || typeof actual === 'boolean' ? actual : null;
+    reason = success ? `${property} matches expected value` : `expected ${property} to match but observed ${String(actual)}`;
+  }
+  else {
+    reason = `unsupported or unavailable state property: ${property}`;
+  }
+  return { success, reason, rawValue, observedValue };
+}