mobile-debug-mcp 0.26.4 → 0.27.0

package/src/observe/ios.ts

@@ -73,6 +73,9 @@ function normalizeIOSType(value: unknown): string {
 
 function inferIOSRole(type: string, traits: string[]): string | null {
   if (/slider|adjustable/.test(type) || traits.some((trait) => /adjustable|slider/.test(trait))) return 'slider'
+  if (/stepper/.test(type)) return 'stepper'
+  if (/picker|pop up button|dropdown/.test(type)) return 'dropdown'
+  if (/segmented control/.test(type)) return 'segmented_control'
   if (/button/.test(type) || traits.some((trait) => /button/.test(trait))) return 'button'
   if (/cell/.test(type)) return 'cell'
   if (/switch/.test(type)) return 'switch'
@@ -113,11 +116,47 @@ function buildIOSSelector(type: string, label: string | null, value: string | nu
   return null
 }
 
-function buildIOSSemantic(type: string, traits: string[]): UIElementSemanticMetadata {
-  return {
+function buildIOSSemantic(type: string, traits: string[], role: string | null, value: string | null): UIElementSemanticMetadata {
+  const semantic: UIElementSemanticMetadata = {
     is_clickable: traits.includes("UIAccessibilityTraitButton") || /adjustable|slider/.test(type) || type === "Button" || type === "Cell",
     is_container: /window|application|group|scroll view|collection view/.test(type)
   }
+
+  if (role === 'slider') {
+    semantic.semantic_role = 'slider'
+    semantic.adjustable = true
+    semantic.supported_actions = ['adjust']
+    semantic.state_shape = 'continuous'
+  } else if (role === 'stepper') {
+    semantic.semantic_role = 'stepper'
+    semantic.adjustable = true
+    semantic.supported_actions = ['increment', 'decrement']
+    semantic.state_shape = 'discrete'
+  } else if (role === 'dropdown') {
+    semantic.semantic_role = 'dropdown'
+    semantic.supported_actions = ['tap', 'expand']
+    semantic.state_shape = 'semantic'
+  } else if (role === 'segmented_control') {
+    semantic.semantic_role = 'segmented_control'
+    semantic.supported_actions = ['tap']
+    semantic.state_shape = 'discrete'
+  } else if (traits.some((trait) => /adjustable|slider/i.test(trait)) || /adjustable|slider/.test(type)) {
+    semantic.semantic_role = 'custom_adjustable'
+    semantic.adjustable = true
+    semantic.supported_actions = ['adjust']
+    semantic.state_shape = 'continuous'
+  } else if (semantic.is_clickable) {
+    semantic.supported_actions = ['tap']
+  }
+
+  if (semantic.state_shape === undefined && semantic.adjustable && value !== null) {
+    const numericValue = parseIOSNumber(value)
+    if (numericValue !== null && numericValue >= 0 && numericValue <= 1) {
+      semantic.state_shape = 'continuous'
+    }
+  }
+
+  return semantic
 }
 
 function isIOSAdjustable(node: IDBElement, type: string, traits: string[]): boolean {
@@ -184,8 +223,8 @@ export function traverseIDBNode(node: IDBElement, elements: UIElement[], parentI
   const normalizedType = normalizeIOSType(type)
   const stableId = getIOSStableId(node)
   const selector = buildIOSSelector(type, label, value, stableId)
-  const semantic = buildIOSSemantic(normalizedType, traits)
   const role = inferIOSRole(normalizedType, traits)
+  const semantic = buildIOSSemantic(normalizedType, traits, role, value)
   
   const clickable = traits.includes("UIAccessibilityTraitButton") || type === "Button" || type === "Cell";
   

package/src/server/common.ts

@@ -1,10 +1,15 @@
 import type {
   ActionExecutionResult,
   ActionFailureCode,
-  ActionTargetResolved
+  ActionTargetResolved,
+  FailureClass,
+  RecoveryState
 } from '../types.js'
 import { ToolsObserve } from '../observe/index.js'
 
+export const DEFAULT_MAX_RECOVERY_ATTEMPTS = 3
+export const DEFAULT_MAX_RETRY_DEPTH = 3
+
 export function wrapResponse<T>(data: T) {
   return {
     content: [{
@@ -103,6 +108,7 @@ export function normalizeResolvedTarget(value: Partial<ActionTargetResolved> | n
 
 export function inferGenericFailure(message: string | undefined): { failureCode: ActionFailureCode; retryable: boolean } {
   if (message && /timeout/i.test(message)) return { failureCode: 'TIMEOUT', retryable: true }
+  if (message && /semantic mismatch/i.test(message)) return { failureCode: 'SEMANTIC_MISMATCH', retryable: false }
   return { failureCode: 'UNKNOWN', retryable: false }
 }
 
@@ -129,6 +135,42 @@ export function determineActionLifecycleState({
   return ACTION_LIFECYCLE_STATE_BY_OUTCOME.success
 }
 
+function mapFailureCodeToFailureClass(code: ActionFailureCode): FailureClass {
+  switch (code) {
+    case 'ELEMENT_NOT_FOUND':
+    case 'AMBIGUOUS_TARGET':
+    case 'STALE_REFERENCE':
+      return 'TargetResolutionFailure'
+    case 'ELEMENT_NOT_INTERACTABLE':
+      return 'ExecutionFailure'
+    case 'TIMEOUT':
+    case 'ACTION_REJECTED':
+    case 'NAVIGATION_NO_CHANGE':
+    case 'UNKNOWN':
+      return 'ExecutionFailure'
+    case 'VERIFICATION_FAILED':
+    case 'EXPECT_STATE_MISMATCH':
+      return 'VerificationFailure'
+    case 'CONTROL_CONVERGENCE_FAILED':
+      return 'ControlConvergenceFailure'
+    case 'SEMANTIC_MISMATCH':
+      return 'SemanticMismatchFailure'
+  }
+}
+
+function buildRecoveryState(failureCode: ActionFailureCode, retryable: boolean): RecoveryState {
+  return {
+    failure_class: mapFailureCodeToFailureClass(failureCode),
+    runtime_code: failureCode,
+    recovery_attempts: 0,
+    max_recovery_attempts: DEFAULT_MAX_RECOVERY_ATTEMPTS,
+    retry_depth: 0,
+    max_retry_depth: DEFAULT_MAX_RETRY_DEPTH,
+    is_terminal: false,
+    retry_allowed: retryable
+  }
+}
+
 export function buildActionExecutionResult({
   actionType,
   device,
@@ -167,6 +209,7 @@ export function buildActionExecutionResult({
     },
     success,
     ...(failure ? { failure_code: failure.failureCode, retryable: failure.retryable } : {}),
+    ...(failure ? { recovery: buildRecoveryState(failure.failureCode, failure.retryable) } : {}),
     ui_fingerprint_before: uiFingerprintBefore,
     ui_fingerprint_after: uiFingerprintAfter,
     ...(details ? { details } : {})

package/src/server-core.ts

@@ -13,7 +13,7 @@ export { wrapResponse, toolDefinitions, handleToolCall }
 
 export const serverInfo = {
   name: 'mobile-debug-mcp',
-  version: '0.26.4'
+  version: '0.27.0'
 }
 
 export function createServer() {

package/src/types.ts

@@ -107,7 +107,25 @@ export interface UIResolutionSelector {
 export interface UIElementSemanticMetadata {
   is_clickable: boolean;
   is_container: boolean;
-}
+  semantic_role?: 'slider' | 'stepper' | 'dropdown' | 'segmented_control' | 'custom_adjustable' | 'composite_control' | null;
+  supported_actions?: string[] | null;
+  adjustable?: boolean | null;
+  state_shape?: 'continuous' | 'discrete' | 'semantic' | null;
+}
+
+export type FailureClass =
+  | 'TargetResolutionFailure'
+  | 'ExecutionFailure'
+  | 'VerificationFailure'
+  | 'ControlConvergenceFailure'
+  | 'SemanticMismatchFailure';
+
+export type RecoveryStrategy =
+  | 're_resolve'
+  | 'alternate_candidate'
+  | 'state_refresh'
+  | 'retry_adjustment'
+  | 'step_back';
 
 export interface LoadingState {
   active: boolean;
@@ -236,8 +254,25 @@ export type ActionFailureCode =
   | 'NAVIGATION_NO_CHANGE'
   | 'AMBIGUOUS_TARGET'
   | 'STALE_REFERENCE'
+  | 'ACTION_REJECTED'
+  | 'VERIFICATION_FAILED'
+  | 'EXPECT_STATE_MISMATCH'
+  | 'CONTROL_CONVERGENCE_FAILED'
+  | 'SEMANTIC_MISMATCH'
   | 'UNKNOWN'
 
+export interface RecoveryState {
+  failure_class: FailureClass;
+  runtime_code: ActionFailureCode;
+  recovery_strategy?: RecoveryStrategy;
+  recovery_attempts: number;
+  max_recovery_attempts: number;
+  retry_depth: number;
+  max_retry_depth: number;
+  is_terminal: boolean;
+  retry_allowed?: boolean;
+}
+
 export interface ActionTargetResolved {
   elementId: string | null;
   text: string | null;
@@ -341,6 +376,7 @@ export interface ActionExecutionResult {
   success: boolean;
   failure_code?: ActionFailureCode;
   retryable?: boolean;
+  recovery?: RecoveryState;
   ui_fingerprint_before?: string | null;
   ui_fingerprint_after?: string | null;
   details?: Record<string, unknown>;
@@ -411,6 +447,10 @@ export interface ExpectStateResponse {
   reason?: string;
   failure_code?: 'ELEMENT_NOT_FOUND' | 'UNKNOWN';
   retryable?: boolean;
+  stabilization_attempts?: number;
+  stabilization_window_ms?: number;
+  stable_observation_count?: number;
+  snapshot_freshness_ms?: number;
 }
 
 export interface AdjustControlResponse extends ActionExecutionResult {

package/src/utils/android/utils.ts

@@ -342,6 +342,9 @@ function normalizeClassName(value: unknown): string {
 
 function inferAndroidRole(className: string): string | null {
   if (/seekbar|slider/.test(className)) return 'slider'
+  if (/stepper|numberpicker/.test(className)) return 'stepper'
+  if (/spinner|dropdown/.test(className)) return 'dropdown'
+  if (/segment|tablayout/.test(className)) return 'segmented_control'
   if (/switch|toggle/.test(className)) return 'switch'
   if (/checkbox/.test(className)) return 'checkbox'
   if (/radiobutton|radio/.test(className)) return 'radio'
@@ -375,11 +378,35 @@ function buildAndroidSelector(text: string | null, contentDescription: string |
   return null
 }
 
-function buildAndroidSemantic(clickable: boolean, className: string): UIElementSemanticMetadata {
-  return {
+function buildAndroidSemantic(clickable: boolean, className: string, role: string | null): UIElementSemanticMetadata {
+  const semantic: UIElementSemanticMetadata = {
     is_clickable: clickable,
     is_container: /recyclerview|scroll|layout|viewgroup|frame/.test(className)
   }
+
+  if (role === 'slider') {
+    semantic.semantic_role = 'slider'
+    semantic.adjustable = true
+    semantic.supported_actions = ['adjust']
+    semantic.state_shape = 'continuous'
+  } else if (role === 'stepper') {
+    semantic.semantic_role = 'stepper'
+    semantic.adjustable = true
+    semantic.supported_actions = ['increment', 'decrement']
+    semantic.state_shape = 'discrete'
+  } else if (role === 'dropdown') {
+    semantic.semantic_role = 'dropdown'
+    semantic.supported_actions = ['tap', 'expand']
+    semantic.state_shape = 'semantic'
+  } else if (role === 'segmented_control') {
+    semantic.semantic_role = 'segmented_control'
+    semantic.supported_actions = ['tap']
+    semantic.state_shape = 'discrete'
+  } else if (clickable) {
+    semantic.supported_actions = ['tap']
+  }
+
+  return semantic
 }
 
 function isSliderLikeAndroid(node: any): boolean {
@@ -459,7 +486,7 @@ export function traverseNode(node: any, elements: UIElement[], parentIndex: numb
     const stableId = resourceId ?? (typeof contentDescription === 'string' && contentDescription.trim().length > 0 ? contentDescription : null)
     const testTag = stableId
     const selector = buildAndroidSelector(text, contentDescription, resourceId, normalizeClassName(className))
-    const semantic = buildAndroidSemantic(clickable, normalizeClassName(className))
+    const semantic = buildAndroidSemantic(clickable, normalizeClassName(className), role)
 
     const isUseful = clickable || (text && text.length > 0) || (contentDescription && contentDescription.length > 0);
 

package/test/unit/interact/adjust_control.test.ts

@@ -346,9 +346,85 @@ async function run() {
     assert.strictEqual(cachedResolveAdjust.success, true)
     assert.strictEqual(cachedResolveAdjust.converged, true)
     assert.strictEqual(cachedResolveAdjust.within_tolerance, true)
-    assert.strictEqual(cachedResolveAdjust.attempts, 3)
+    assert.ok(cachedResolveAdjust.attempts >= 3)
     assert.strictEqual(treeFetches, 1, 'second attempt should reuse the resolved element instead of refetching the UI tree')
 
+    const probeTapStart = tapCalls.length
+    const probeSwipeStart = swipeCalls.length
+    let probeVerificationCount = 0
+    ;(Observe as any).ToolsObserve.getUITreeHandler = async () => ({
+      device: { platform: 'android', id: 'mock-device', osVersion: '14', model: 'Pixel', simulator: true },
+      screen: '',
+      resolution: { width: 1080, height: 2400 },
+      elements: [
+        {
+          text: 'Duration',
+          type: 'android.widget.SeekBar',
+          contentDescription: null,
+          clickable: true,
+          enabled: true,
+          visible: true,
+          bounds: [0, 0, 200, 40],
+          resourceId: 'seek_duration',
+          state: {
+            value: 10,
+            raw_value: 10,
+            value_range: { min: 0, max: 20 }
+          }
+        }
+      ]
+    })
+
+    ;(ToolsInteract as any).tapHandler = async ({ platform, x, y, deviceId }: any) => {
+      tapCalls.push({ platform, x, y, deviceId })
+      return {
+        device: { platform: platform || 'android', id: deviceId || 'mock-device', osVersion: '14', model: 'Pixel', simulator: true },
+        success: true,
+        x,
+        y
+      }
+    }
+
+    ;(ToolsInteract as any).expectStateHandler = async () => {
+      probeVerificationCount++
+      const value = probeVerificationCount === 1 ? 11 : 12
+      return {
+        success: true,
+        selector: { text: 'Duration' },
+        element_id: wait.element.elementId,
+        expected_state: { property: 'value', expected: 12 },
+        element: {
+          elementId: wait.element.elementId,
+          text: 'Duration',
+          resource_id: 'seek_duration',
+          accessibility_id: null,
+          class: 'android.widget.SeekBar',
+          bounds: [0, 0, 200, 40],
+          index: 0,
+          state: { value, raw_value: value, value_range: { min: 0, max: 20 } }
+        },
+        observed_state: { property: 'value', value, raw_value: value },
+        reason: value === 12 ? 'value matches expected value' : 'value still below target'
+      }
+    }
+
+    const probeAdjust = await ToolsInteract.adjustControlHandler({
+      element_id: wait.element.elementId,
+      property: 'value',
+      targetValue: 12,
+      tolerance: 0.5,
+      maxAttempts: 3,
+      platform: 'android'
+    })
+
+    assert.strictEqual(probeAdjust.success, true)
+    assert.strictEqual(probeAdjust.converged, true)
+    assert.strictEqual(probeAdjust.within_tolerance, true)
+    assert.strictEqual(probeAdjust.adjustment_mode, 'coordinate')
+    assert.strictEqual(probeAdjust.attempts, 2)
+    assert.strictEqual(tapCalls.length, probeTapStart + 2)
+    assert.strictEqual(swipeCalls.length, probeSwipeStart)
+
     console.log('adjust_control unit tests passed')
   } finally {
     ;(Observe as any).ToolsObserve.getUITreeHandler = originalGetUITreeHandler

package/test/unit/interact/verification_stabilization.test.ts

@@ -0,0 +1,94 @@
+import assert from 'assert'
+import { ToolsInteract } from '../../../src/interact/index.js'
+import * as Observe from '../../../src/observe/index.js'
+
+async function run() {
+  console.log('Starting verification stabilization unit tests...')
+
+  const originalGetUITreeHandler = (Observe as any).ToolsObserve.getUITreeHandler
+
+  try {
+    let visibilityCalls = 0
+    ;(Observe as any).ToolsObserve.getUITreeHandler = async () => {
+      visibilityCalls++
+      const visible = visibilityCalls >= 3
+      return {
+        device: { platform: 'android', id: 'mock-device', osVersion: '14', model: 'Pixel', simulator: true },
+        captured_at_ms: Date.now(),
+        resolution: { width: 1080, height: 2400 },
+        elements: [
+          {
+            text: visible ? 'Ready' : 'Loading',
+            contentDescription: null,
+            type: 'android.widget.TextView',
+            resourceId: 'ready_label',
+            clickable: false,
+            enabled: true,
+            visible,
+            bounds: [0, 0, 120, 40]
+          }
+        ]
+      }
+    }
+
+    const visibleResult = await ToolsInteract.waitForUIHandler({
+      selector: { text: 'Ready' },
+      condition: 'visible',
+      timeout_ms: 600,
+      poll_interval_ms: 50,
+      platform: 'android'
+    })
+
+    assert.strictEqual(visibleResult.status, 'success')
+    assert.ok(visibilityCalls >= 4, 'visibility should be confirmed across consecutive reads')
+
+    let stateCalls = 0
+    ;(Observe as any).ToolsObserve.getUITreeHandler = async () => {
+      stateCalls++
+      const value = stateCalls >= 3 ? 30 : 10
+      const stale = stateCalls === 2
+      return {
+        device: { platform: 'android', id: 'mock-device', osVersion: '14', model: 'Pixel', simulator: true },
+        captured_at_ms: stale ? Date.now() - 1000 : Date.now(),
+        resolution: { width: 1080, height: 2400 },
+        elements: [
+          {
+            text: 'Volume',
+            contentDescription: null,
+            type: 'android.widget.SeekBar',
+            resourceId: 'volume_slider',
+            clickable: true,
+            enabled: true,
+            visible: true,
+            bounds: [0, 0, 240, 40],
+            state: {
+              value,
+              raw_value: value,
+              value_range: { min: 0, max: 100 }
+            }
+          }
+        ]
+      }
+    }
+
+    const stateResult = await ToolsInteract.expectStateHandler({
+      selector: { text: 'Volume' },
+      property: 'value',
+      expected: 30,
+      platform: 'android'
+    })
+
+    assert.strictEqual(stateResult.success, true)
+    assert.strictEqual(stateResult.reason, 'value matches expected value')
+    assert.ok(stateCalls >= 4, 'state verification should require stable fresh reads')
+
+    console.log('verification stabilization unit tests passed')
+  } finally {
+    ;(Observe as any).ToolsObserve.getUITreeHandler = originalGetUITreeHandler
+  }
+}
+
+run().catch((error) => {
+  console.error(error)
+  process.exit(1)
+})

package/test/unit/observe/find_element.test.ts

@@ -78,6 +78,52 @@ async function run() {
     assert.ok((res4.resolution?.alternates || []).length >= 1, 'Parent promotion should preserve alternates')
     process.stdout.write('Test 4: ' + (pass4 ? 'PASS' : 'FAIL') + '\n');
 
+    // Test 4b: semantic-only stepper should be discoverable by supported action
+    ;(ToolsObserve as any).getUITreeHandler = async () => ({
+      device: { platform: 'android', id: 'mock' },
+      screen: '',
+      resolution: { width: 1080, height: 1920 },
+      elements: [
+        {
+          text: null,
+          contentDescription: 'Quantity stepper',
+          type: 'android.widget.NumberPicker',
+          clickable: false,
+          enabled: true,
+          visible: true,
+          bounds: [10,10,200,80],
+          resourceId: 'picker_quantity',
+          semantic: {
+            is_clickable: false,
+            is_container: true,
+            semantic_role: 'stepper',
+            supported_actions: ['increment', 'decrement'],
+            adjustable: true,
+            state_shape: 'discrete'
+          }
+        }
+      ]
+    })
+
+    const res4b: any = await ToolsInteract.findElementHandler({ query: 'increment', exact: false, platform: 'android', timeoutMs: 300 })
+    process.stdout.write('res4b ' + JSON.stringify(res4b, null, 2) + '\n');
+    const pass4b = res4b.found === true && res4b.element && res4b.element.resourceId === 'picker_quantity' && res4b.element.semantic?.semantic_role === 'stepper'
+    assert.ok(pass4b, 'Semantic-only steppers should be discoverable by supported actions')
+    assert.strictEqual(res4b.resolution?.reason, 'semantic_action_match')
+    process.stdout.write('Test 4b: ' + (pass4b ? 'PASS' : 'FAIL') + '\n');
+
+    const res4bb: any = await ToolsInteract.findElementHandler({ query: 'increment', exact: true, platform: 'android', timeoutMs: 300 })
+    process.stdout.write('res4bb ' + JSON.stringify(res4bb, null, 2) + '\n');
+    const pass4bb = res4bb.found === true && res4bb.element && res4bb.element.resourceId === 'picker_quantity' && res4bb.resolution?.reason === 'semantic_action_match'
+    assert.ok(pass4bb, 'Exact searches should still match exact semantic actions')
+    process.stdout.write('Test 4bb: ' + (pass4bb ? 'PASS' : 'FAIL') + '\n');
+
+    const res4c: any = await ToolsInteract.findElementHandler({ query: 'control', exact: true, platform: 'android', timeoutMs: 300 })
+    process.stdout.write('res4c ' + JSON.stringify(res4c, null, 2) + '\n');
+    const pass4c = res4c.found === false
+    assert.ok(pass4c, 'Exact searches should not fall back to broad semantic keywords')
+    process.stdout.write('Test 4c: ' + (pass4c ? 'PASS' : 'FAIL') + '\n');
+
     // Test 5: duration label should resolve to the nearby slider control
     ;(ToolsObserve as any).getUITreeHandler = async () => ({
       device: { platform: 'android', id: 'mock' },

package/test/unit/observe/state_extraction.test.ts

@@ -29,7 +29,14 @@ async function run() {
     value: 'com.example:id/duration',
     confidence: { score: 1, reason: 'resource_id' }
   })
-  assert.deepStrictEqual(androidElements[0].semantic, { is_clickable: true, is_container: false })
+  assert.deepStrictEqual(androidElements[0].semantic, {
+    is_clickable: true,
+    is_container: false,
+    semantic_role: 'slider',
+    supported_actions: ['adjust'],
+    adjustable: true,
+    state_shape: 'continuous'
+  })
 
   const androidProgressElements: any[] = []
   traverseNode({
@@ -44,6 +51,21 @@ async function run() {
 
   assert.notStrictEqual(androidProgressElements[0]?.role, 'slider')
   assert.notStrictEqual(androidProgressElements[0]?.state?.value, 40)
+  assert.notStrictEqual(androidProgressElements[0]?.semantic?.adjustable, true)
+
+  const androidStepperElements: any[] = []
+  traverseNode({
+    '@_class': 'android.widget.NumberPicker',
+    '@_text': 'Quantity',
+    '@_content-desc': 'Quantity stepper',
+    '@_clickable': 'false',
+    '@_enabled': 'true',
+    '@_bounds': '[0,0][200,80]'
+  }, androidStepperElements)
+  assert.strictEqual(androidStepperElements[0].role, 'stepper')
+  assert.deepStrictEqual(androidStepperElements[0].semantic?.semantic_role, 'stepper')
+  assert.deepStrictEqual(androidStepperElements[0].semantic?.supported_actions, ['increment', 'decrement'])
+  assert.strictEqual(androidStepperElements[0].semantic?.adjustable, true)
 
   const androidFallbackElements: any[] = []
   traverseNode({
@@ -82,7 +104,14 @@ async function run() {
     value: 'playback_speed_slider',
     confidence: { score: 1, reason: 'accessibility_identifier' }
   })
-  assert.deepStrictEqual(iosElements[0].semantic, { is_clickable: true, is_container: false })
+  assert.deepStrictEqual(iosElements[0].semantic, {
+    is_clickable: true,
+    is_container: false,
+    semantic_role: 'slider',
+    supported_actions: ['adjust'],
+    adjustable: true,
+    state_shape: 'continuous'
+  })
 
   const iosProgressElements: any[] = []
   traverseIDBNode({
@@ -94,6 +123,40 @@ async function run() {
 
   assert.notStrictEqual(iosProgressElements[0]?.role, 'slider')
 
+  const iosStepperElements: any[] = []
+  traverseIDBNode({
+    AXElementType: 'Stepper',
+    AXLabel: 'Quantity',
+    AXValue: '1',
+    AXTraits: ['UIAccessibilityTraitAdjustable']
+  }, iosStepperElements)
+  assert.strictEqual(iosStepperElements[0].role, 'stepper')
+  assert.strictEqual(iosStepperElements[0].semantic?.semantic_role, 'stepper')
+  assert.deepStrictEqual(iosStepperElements[0].semantic?.supported_actions, ['increment', 'decrement'])
+  assert.strictEqual(iosStepperElements[0].semantic?.state_shape, 'discrete')
+
+  const iosSegmentedElements: any[] = []
+  traverseIDBNode({
+    AXElementType: 'Segmented Control',
+    AXLabel: 'Playback mode',
+    AXTraits: ['UIAccessibilityTraitButton']
+  }, iosSegmentedElements)
+  assert.strictEqual(iosSegmentedElements[0].role, 'segmented_control')
+  assert.strictEqual(iosSegmentedElements[0].semantic?.semantic_role, 'segmented_control')
+  assert.deepStrictEqual(iosSegmentedElements[0].semantic?.supported_actions, ['tap'])
+
+  const iosCustomAdjustableElements: any[] = []
+  traverseIDBNode({
+    AXElementType: 'CustomControl',
+    AXLabel: 'Intensity',
+    AXValue: '0.25',
+    AXTraits: ['UIAccessibilityTraitAdjustable']
+  }, iosCustomAdjustableElements)
+  assert.strictEqual(iosCustomAdjustableElements[0].semantic?.semantic_role, 'custom_adjustable')
+  assert.strictEqual(iosCustomAdjustableElements[0].semantic?.adjustable, true)
+  assert.deepStrictEqual(iosCustomAdjustableElements[0].semantic?.supported_actions, ['adjust'])
+  assert.strictEqual(iosCustomAdjustableElements[0].semantic?.state_shape, 'continuous')
+
   const iosFallbackElements: any[] = []
   traverseIDBNode({
     AXElementType: 'Button',

package/test/unit/server/common.test.ts

@@ -1,5 +1,5 @@
 import assert from 'assert'
-import { requireBooleanArg } from '../../../src/server/common.js'
+import { buildActionExecutionResult, inferGenericFailure, requireBooleanArg } from '../../../src/server/common.js'
 
 function run() {
   assert.strictEqual(requireBooleanArg({ exact: true }, 'exact'), true)
@@ -7,6 +7,41 @@ function run() {
   assert.throws(() => requireBooleanArg({}, 'exact'), /Missing or invalid boolean argument: exact/)
   assert.throws(() => requireBooleanArg({ exact: 'true' as unknown as boolean }, 'exact'), /Missing or invalid boolean argument: exact/)
 
+  assert.deepStrictEqual(inferGenericFailure('semantic mismatch between inferred and raw state'), {
+    failureCode: 'SEMANTIC_MISMATCH',
+    retryable: false
+  })
+
+  const recoveryResult = buildActionExecutionResult({
+    actionType: 'tap',
+    sourceModule: 'server',
+    selector: { x: 10, y: 20 },
+    success: false,
+    uiFingerprintBefore: 'fp_before',
+    uiFingerprintAfter: 'fp_after',
+    failure: { failureCode: 'SEMANTIC_MISMATCH', retryable: false }
+  })
+  assert.strictEqual(recoveryResult.failure_code, 'SEMANTIC_MISMATCH')
+  assert.strictEqual(recoveryResult.recovery?.failure_class, 'SemanticMismatchFailure')
+  assert.strictEqual(recoveryResult.recovery?.runtime_code, 'SEMANTIC_MISMATCH')
+  assert.strictEqual(recoveryResult.recovery?.retry_allowed, false)
+  assert.strictEqual(recoveryResult.recovery?.max_recovery_attempts, 3)
+  assert.strictEqual(recoveryResult.recovery?.max_retry_depth, 3)
+
+  const notInteractableResult = buildActionExecutionResult({
+    actionType: 'tap',
+    sourceModule: 'server',
+    selector: { x: 5, y: 5 },
+    success: false,
+    uiFingerprintBefore: 'fp_before',
+    uiFingerprintAfter: 'fp_after',
+    failure: { failureCode: 'ELEMENT_NOT_INTERACTABLE', retryable: true }
+  })
+  assert.strictEqual(notInteractableResult.failure_code, 'ELEMENT_NOT_INTERACTABLE')
+  assert.strictEqual(notInteractableResult.recovery?.failure_class, 'ExecutionFailure')
+  assert.strictEqual(notInteractableResult.recovery?.runtime_code, 'ELEMENT_NOT_INTERACTABLE')
+  assert.strictEqual(notInteractableResult.recovery?.retry_allowed, true)
+
   console.log('server common tests passed')
 }