mobile-debug-mcp 0.33.0 → 0.35.0

package/src/utils/android/commands.ts

@@ -0,0 +1,81 @@
+import { existsSync } from 'fs'
+import path from 'path'
+import { execCmd } from '../exec.js'
+import { spawnSync } from 'child_process'
+import type { SpawnOptions } from 'child_process'
+export function findInPath(cmd: string): string | null {
+  try {
+    // prefer command -v for POSIX
+    const res = spawnSync('command', ['-v', cmd], { encoding: 'utf8' })
+    if (res.status === 0 && res.stdout) return res.stdout.trim()
+  } catch (e: unknown) { console.debug(`[findInPath] command -v ${cmd} failed: ${String(e)}`) }
+  try {
+    const res = spawnSync('which', [cmd], { encoding: 'utf8' })
+    if (res.status === 0 && res.stdout) return res.stdout.trim()
+  } catch (e: unknown) { console.debug(`[findInPath] which ${cmd} failed: ${String(e)}`) }
+  return null
+}
+
+export function resolveAdbCmd(): string {
+  // Priority: explicit env ADB_PATH -> PATH -> known SDK locations -> fallback to 'adb'
+  if (process.env.ADB_PATH && process.env.ADB_PATH.trim()) return process.env.ADB_PATH
+  const found = findInPath('adb')
+  if (found) return found
+  const sdkRoot = process.env.ANDROID_SDK_ROOT || process.env.ANDROID_HOME
+  if (sdkRoot) {
+    const candidate = path.join(sdkRoot, 'platform-tools', process.platform === 'win32' ? 'adb.exe' : 'adb')
+    if (existsSync(candidate)) return candidate
+  }
+  // common macOS user SDK path
+  const homeSdk = path.join(process.env.HOME || '', 'Library', 'Android', 'sdk', 'platform-tools', process.platform === 'win32' ? 'adb.exe' : 'adb')
+  if (existsSync(homeSdk)) return homeSdk
+  return 'adb'
+}
+
+export function getAdbCmd() { return resolveAdbCmd() }
+
+export function ensureAdbAvailable() {
+  const adb = resolveAdbCmd()
+  try {
+    const res = spawnSync(adb, ['--version'], { encoding: 'utf8' })
+    if (res.status === 0) {
+      return { adbCmd: adb, ok: true, version: (res.stdout || res.stderr || '').trim() }
+    }
+    return { adbCmd: adb, ok: false, error: (res.stderr || res.stdout || '').trim() }
+  } catch (err: unknown) {
+    return { adbCmd: adb, ok: false, error: String(err) }
+  }
+}
+
+export function getAdbArgs(args: string[], deviceId?: string): string[] {
+  if (deviceId) {
+    return ['-s', deviceId, ...args]
+  }
+  return args
+}
+
+export function getAdbTimeout(args: string[], customTimeout?: number): number {
+  if (typeof customTimeout === 'number' && !isNaN(customTimeout)) return customTimeout
+  const envTimeout = parseInt(process.env.MCP_ADB_TIMEOUT || process.env.ADB_TIMEOUT || '', 10)
+  if (!isNaN(envTimeout) && envTimeout > 0) return envTimeout
+  if (args.includes('logcat')) return 10000
+  if (args.includes('uiautomator') && args.includes('dump')) return 20000
+  return 120000
+}
+
+export type SpawnOptionsWithTimeout = SpawnOptions & { timeout?: number }
+
+export async function execAdb(args: string[], deviceId?: string, options: SpawnOptionsWithTimeout = {}): Promise<string> {
+  const adbArgs = getAdbArgs(args, deviceId)
+  const timeoutMs = getAdbTimeout(args, options.timeout)
+  const res = await execCmd(getAdbCmd(), adbArgs, { timeout: timeoutMs, env: options.env, cwd: typeof options.cwd === 'string' ? options.cwd : undefined, shell: !!options.shell })
+  if (res.exitCode !== 0) throw new Error(res.stderr || `Command failed with code ${res.exitCode}`)
+  return res.stdout
+}
+
+export async function spawnAdb(args: string[], deviceId?: string, options: SpawnOptionsWithTimeout = {}): Promise<{ stdout: string, stderr: string, code: number | null }> {
+  const adbArgs = getAdbArgs(args, deviceId)
+  const timeoutMs = getAdbTimeout(args, options.timeout)
+  const res = await execCmd(getAdbCmd(), adbArgs, { timeout: timeoutMs, env: options.env, cwd: typeof options.cwd === 'string' ? options.cwd : undefined, shell: !!options.shell })
+  return { stdout: res.stdout, stderr: res.stderr, code: res.exitCode }
+}

package/src/utils/android/gradle.ts

@@ -0,0 +1,132 @@
+import { promises as fsPromises, existsSync } from 'fs'
+import path from 'path'
+import { detectJavaHome } from '../java.js'
+import { checkGradle } from '../../system/gradle.js'
+import { resolveAdbCmd } from './commands.js'
+export type GradleEnvOverrides = Record<string, string | undefined>
+
+export function mergeEnv(overrides?: GradleEnvOverrides) {
+  const env: Record<string, string> = {}
+  for (const [key, value] of Object.entries(process.env)) {
+    if (typeof value === 'string') env[key] = value
+  }
+  for (const [key, value] of Object.entries(overrides || {})) {
+    if (typeof value === 'string') env[key] = value
+  }
+  return env
+}
+
+export async function prepareGradle(projectPath: string, envOverrides: GradleEnvOverrides = {}): Promise<{ execCmd: string, gradleArgs: string[], spawnOpts: import('node:child_process').SpawnOptions }> {
+  const env = mergeEnv(envOverrides)
+  const gradlewPath = path.join(projectPath, 'gradlew')
+  const gradleCmd = existsSync(gradlewPath) ? './gradlew' : 'gradle'
+  const execCmd = existsSync(gradlewPath) ? gradlewPath : gradleCmd
+
+  // Start with a default task; callers may append/override via env flags
+  const gradleArgs: string[] = [env.MCP_GRADLE_TASK || 'assembleDebug']
+
+  // Respect generic MCP_BUILD_JOBS and Android-specific MCP_GRADLE_WORKERS
+  const workers = env.MCP_GRADLE_WORKERS || env.MCP_BUILD_JOBS
+  if (workers) {
+    gradleArgs.push(`--max-workers=${workers}`)
+  }
+
+  // Respect gradle cache env: default enabled; set MCP_GRADLE_CACHE=0 to disable
+  if (env.MCP_GRADLE_CACHE === '0') {
+    gradleArgs.push('-Dorg.gradle.caching=false')
+  }
+
+  const detectedJavaHome = await detectJavaHome().catch(() => undefined)
+  // Check for problematic org.gradle.java.home entries (env or properties) and avoid passing invalid values to Gradle
+  let gradleCheck
+  try {
+    gradleCheck = await checkGradle()
+  } catch {
+    gradleCheck = { gradleJavaHome: undefined, gradleValid: false, filesChecked: [], issues: [] }
+  }
+
+  // Ensure child processes can find Android platform-tools (adb, etc.) by
+  // prepending the platform-tools directory to PATH for spawned processes.
+  const adbPath = resolveAdbCmd()
+  let platformToolsDir: string | undefined = undefined
+  try {
+    if (adbPath && adbPath !== 'adb' && existsSync(adbPath)) {
+      platformToolsDir = path.dirname(adbPath)
+    }
+  } catch (e: unknown) { console.debug(`[prepareGradle] error resolving adbPath: ${String(e)}`) }
+
+  const pathParts: string[] = []
+  configureJava(env, gradleArgs, pathParts, detectedJavaHome, gradleCheck)
+
+  configurePlatformTools(env, pathParts, platformToolsDir)
+
+  if (pathParts.length > 0) {
+    env.PATH = `${pathParts.join(path.delimiter)}${path.delimiter}${env.PATH || ''}`
+  }
+
+  try { delete env.SHELL } catch (e: unknown) { console.debug('[prepareGradle] failed to delete SHELL from env:', String(e)) }
+
+  const useWrapper = existsSync(gradlewPath)
+  const spawnOpts: import('node:child_process').SpawnOptions = { cwd: projectPath, env }
+  if (useWrapper) {
+    try { await fsPromises.chmod(gradlewPath, 0o755) } catch (e: unknown) { console.debug('[prepareGradle] chmod failed for gradlew:', String(e)) }
+    // Execute the wrapper directly without a shell to avoid shell tokenization of args (spaces in paths)
+    spawnOpts.shell = false
+  } else {
+    // Prefer executing gradle directly without invoking a shell to preserve argument boundaries
+    spawnOpts.shell = false
+  }
+
+  return { execCmd, gradleArgs, spawnOpts }
+}
+
+function configureJava(env: Record<string, string>, gradleArgs: string[], pathParts: string[], detectedJavaHome: string | undefined, gradleCheck: { gradleJavaHome?: string; gradleValid: boolean }) {
+  // Prefer a detected (validated) Java home from the system/IDE
+  if (detectedJavaHome) {
+    if (env.JAVA_HOME !== detectedJavaHome) {
+      env.JAVA_HOME = detectedJavaHome
+    }
+    const javaBin = path.join(detectedJavaHome, 'bin')
+    pathParts.push(javaBin)
+    gradleArgs.push(`-Dorg.gradle.java.home=${detectedJavaHome}`)
+    gradleArgs.push('--no-daemon')
+    env.GRADLE_JAVA_HOME = detectedJavaHome
+  } else if (gradleCheck && gradleCheck.gradleJavaHome) {
+    // There's an org.gradle.java.home configured somewhere (env or gradle.properties)
+    if (gradleCheck.gradleValid) {
+      const p = gradleCheck.gradleJavaHome as string
+      const javaBin = path.join(p, 'bin')
+      if (!env.PATH || !env.PATH.includes(javaBin)) pathParts.push(javaBin)
+      gradleArgs.push(`-Dorg.gradle.java.home=${p}`)
+      gradleArgs.push('--no-daemon')
+      env.GRADLE_JAVA_HOME = p
+    } else {
+      // Invalid gradle java home detected: avoid passing it to Gradle and remove from spawn env
+      console.debug(`[prepareGradle] Invalid org.gradle.java.home detected (${gradleCheck.gradleJavaHome}); removing from spawn env to avoid Gradle error.`)
+      try { delete env.GRADLE_JAVA_HOME } catch { }
+    }
+  }
+
+}
+
+function configurePlatformTools(env: Record<string, string>, pathParts: string[], platformToolsDir: string | undefined) {
+  if (platformToolsDir) {
+    // Prepend platform-tools so gradle and child tools find adb without modifying global env
+    if (!env.PATH || !env.PATH.includes(platformToolsDir)) {
+      pathParts.push(platformToolsDir)
+    }
+  } else if (process.env.ANDROID_SDK_ROOT || process.env.ANDROID_HOME) {
+    const sdkRoot = process.env.ANDROID_SDK_ROOT || process.env.ANDROID_HOME || ''
+    const candidate = path.join(sdkRoot, 'platform-tools')
+    if (existsSync(candidate) && (!env.PATH || !env.PATH.includes(candidate))) {
+      pathParts.push(candidate)
+    }
+  } else {
+    // also try common user sdk location
+    const homeSdkTools = path.join(process.env.HOME || '', 'Library', 'Android', 'sdk', 'platform-tools')
+    if (existsSync(homeSdkTools) && (!env.PATH || !env.PATH.includes(homeSdkTools))) {
+      pathParts.push(homeSdkTools)
+    }
+  }
+
+}

package/src/utils/android/logs.ts

@@ -0,0 +1,103 @@
+interface AndroidLogEntry {
+  timestamp: string; level: string; tag: string; message: string; _iso: string | null
+  crash: boolean; exception?: string; pid?: string; tid?: string
+}
+export function parseLogLine(line: string) {  // Collapse internal newlines so multiline stack traces are parseable as a single entry
+  const rawLine = line
+  const normalizedLine = rawLine.replace(/\r?\n/g, ' ')
+  const entry: AndroidLogEntry = { timestamp: '', level: '', tag: '', message: rawLine, _iso: null, crash: false }
+
+  const nowYear = new Date().getFullYear()
+
+  const tryIso = (ts: string) => {
+    if (!ts) return null
+    // If it's already ISO
+    if (/^\d{4}-\d{2}-\d{2}T/.test(ts)) return ts
+    // If format MM-DD HH:MM:SS(.sss)
+    const m = ts.match(/^(\d{2})-(\d{2})\s+(\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?)$/)
+    if (m) {
+      const month = m[1]
+      const day = m[2]
+      const time = m[3]
+      const candidate = `${nowYear}-${month}-${day}T${time}`
+      const d = new Date(candidate)
+      if (!isNaN(d.getTime())) return d.toISOString()
+    }
+    // If format YYYY-MM-DD HH:MM:SS(.sss)
+    const m2 = ts.match(/^(\d{4}-\d{2}-\d{2})\s+(\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?)$/)
+    if (m2) {
+      const candidate = `${m2[1]}T${m2[2]}`
+      const d = new Date(candidate)
+      if (!isNaN(d.getTime())) return d.toISOString()
+    }
+    return null
+  }
+
+  // Patterns to try (ordered)
+  const patterns: Array<{ re: RegExp, groups: string[] }> = [
+    // MM-DD HH:MM:SS.mmm PID TID LEVEL/Tag: msg
+    { re: /^(\d{2}-\d{2}\s+\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?)\s+(\d+)\s+(\d+)\s+([VDIWE])\/([^:]+):\s*(.*)$/, groups: ['ts', 'pid', 'tid', 'level', 'tag', 'msg'] },
+    // MM-DD HH:MM:SS.mmm PID TID LEVEL Tag: msg  (space between level and tag)
+    { re: /^(\d{2}-\d{2}\s+\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?)\s+(\d+)\s+(\d+)\s+([VDIWE])\s+([^:]+):\s*(.*)$/, groups: ['ts', 'pid', 'tid', 'level', 'tag', 'msg'] },
+    // YYYY-MM-DD full date with PID TID LEVEL/Tag
+    { re: /^(\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?)\s+(\d+)\s+(\d+)\s+([VDIWE])\/([^:]+):\s*(.*)$/, groups: ['ts', 'pid', 'tid', 'level', 'tag', 'msg'] },
+    // YYYY-MM-DD with space separation
+    { re: /^(\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?)\s+(\d+)\s+(\d+)\s+([VDIWE])\s+([^:]+):\s*(.*)$/, groups: ['ts', 'pid', 'tid', 'level', 'tag', 'msg'] },
+    // MM-DD PID LEVEL/Tag: msg
+    { re: /^(\d{2}-\d{2}\s+\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?)\s+(\d+)\s+([VDIWE])\/([^:]+):\s*(.*)$/, groups: ['ts', 'pid', 'level', 'tag', 'msg'] },
+    // MM-DD PID LEVEL Tag: msg (space)
+    { re: /^(\d{2}-\d{2}\s+\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?)\s+(\d+)\s+([VDIWE])\s+([^:]+):\s*(.*)$/, groups: ['ts', 'pid', 'level', 'tag', 'msg'] },
+    // Short form LEVEL/Tag: msg
+    { re: /^([VDIWE])\/([^\(\:]+)(?:\([0-9]+\))?:\s*(.*)$/, groups: ['level', 'tag', 'msg'] },
+    // Short form LEVEL Tag: msg
+    { re: /^([VDIWE])\s+([^\(\:]+)(?:\([0-9]+\))?:\s*(.*)$/, groups: ['level', 'tag', 'msg'] },
+  ]
+
+  for (const p of patterns) {
+    const m = normalizedLine.match(p.re)
+    if (m) {
+      const g = p.groups
+      const vals: Record<string, string> = {}
+      for (let i = 0; i < g.length; i++) vals[g[i]] = m[i + 1]
+      const ts = vals.ts
+      if (ts) {
+        const iso = tryIso(ts)
+        if (iso) {
+          entry.timestamp = ts
+          entry._iso = iso
+        } else {
+          entry.timestamp = ts
+        }
+      }
+      if (vals.level) entry.level = vals.level
+      if (vals.tag) entry.tag = vals.tag.trim()
+      entry.message = vals.msg || entry.message
+      // Crash heuristics
+      const msg = (entry.message || '').toString()
+      const crash = /FATAL EXCEPTION/i.test(msg) || /\b([A-Za-z0-9_$.]+Exception)\b/.test(msg)
+      if (crash) {
+        entry.crash = true
+        const exMatch = msg.match(/\b([A-Za-z0-9_$.]+Exception)\b/)
+        if (exMatch) entry.exception = exMatch[1]
+      }
+      return entry
+    }
+  }
+
+  // No pattern matched: attempt to extract level/tag like '... E/Tag: msg'
+  const alt = normalizedLine.match(/([VDIWE])\/([^:]+):\s*(.*)$/)
+  if (alt) {
+    entry.level = alt[1]
+    entry.tag = alt[2].trim()
+    entry.message = alt[3]
+    const msg = entry.message
+    const crash = /FATAL EXCEPTION/i.test(msg) || /\b([A-Za-z0-9_$.]+Exception)\b/.test(msg)
+    if (crash) {
+      entry.crash = true
+      const exMatch = msg.match(/\b([A-Za-z0-9_$.]+Exception)\b/)
+      if (exMatch) entry.exception = exMatch[1]
+    }
+  }
+
+  return entry
+}

package/src/utils/android/ui-tree.ts

@@ -0,0 +1,239 @@
+export interface AndroidXMLNode {
+  [key: string]: unknown
+  '@_class'?: string; '@_text'?: string; '@_content-desc'?: string; '@_resource-id'?: string; '@_bounds'?: string
+  '@_clickable'?: string | boolean; '@_enabled'?: string | boolean; '@_visible-to-user'?: string | boolean
+  node?: AndroidXMLNode | AndroidXMLNode[]
+}
+import { UIElement, UIElementSemanticMetadata, UIElementState, UIResolutionSelector, SelectorConfidence } from "../../types.js"
+export function parseBounds(bounds: string): [number, number, number, number] {
+  const match = bounds.match(/\[(\d+),(\d+)\]\[(\d+),(\d+)\]/);
+  if (match) {
+    return [parseInt(match[1]), parseInt(match[2]), parseInt(match[3]), parseInt(match[4])];
+  }
+  return [0, 0, 0, 0];
+}
+
+export function getCenter(bounds: [number, number, number, number]): [number, number] {
+  const [x1, y1, x2, y2] = bounds;
+  return [Math.floor((x1 + x2) / 2), Math.floor((y1 + y2) / 2)];
+}
+
+export function parseBooleanAttr(value: unknown): boolean | null {
+  if (value === true || value === 'true') return true
+  if (value === false || value === 'false') return false
+  return null
+}
+
+export function parseNumberAttr(value: unknown): number | null {
+  if (typeof value === 'number' && Number.isFinite(value)) return value
+  if (typeof value !== 'string') return null
+  const parsed = Number(value)
+  return Number.isFinite(parsed) ? parsed : null
+}
+
+export function normalizeClassName(value: unknown): string {
+  return typeof value === 'string' ? value.trim().toLowerCase() : ''
+}
+
+export 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'
+  if (/edittext|textfield|search/.test(className)) return 'text_field'
+  if (/button|fab/.test(className)) return 'button'
+  if (/imageview|icon/.test(className)) return 'image'
+  if (/recyclerview|scroll|layout|viewgroup|frame/.test(className)) return 'container'
+  return null
+}
+
+export function buildAndroidSelectorConfidence(source: 'resource_id' | 'content_desc' | 'text' | 'class' | 'none'): SelectorConfidence | null {
+  switch (source) {
+    case 'resource_id':
+      return { score: 1, reason: 'resource_id' }
+    case 'content_desc':
+      return { score: 0.9, reason: 'content_description' }
+    case 'text':
+      return { score: 0.6, reason: 'text_match' }
+    case 'class':
+      return { score: 0.35, reason: 'class_match' }
+    default:
+      return null
+  }
+}
+
+export function buildAndroidSelector(text: string | null, contentDescription: string | null, resourceId: string | null, className: string): UIResolutionSelector | null {
+  if (resourceId) return { value: resourceId, confidence: buildAndroidSelectorConfidence('resource_id') }
+  if (contentDescription) return { value: contentDescription, confidence: buildAndroidSelectorConfidence('content_desc') }
+  if (text) return { value: text, confidence: buildAndroidSelectorConfidence('text') }
+  if (className) return { value: className, confidence: buildAndroidSelectorConfidence('class') }
+  return null
+}
+
+export 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
+}
+
+export function isSliderLikeAndroid(node: AndroidXMLNode): boolean {
+  const className = String(node['@_class'] || '').toLowerCase()
+  return /seekbar|slider|range/i.test(className)
+}
+
+export function extractAndroidState(node: AndroidXMLNode): UIElementState | null {
+  const checked = parseBooleanAttr(node['@_checked'])
+  const selectedFlag = parseBooleanAttr(node['@_selected'])
+  const focused = parseBooleanAttr(node['@_focused'])
+  const expanded = parseBooleanAttr(node['@_expanded'])
+  const enabled = parseBooleanAttr(node['@_enabled'])
+  const textValue = typeof node['@_text'] === 'string' && node['@_text'].trim().length > 0 ? node['@_text'] : null
+  const state: UIElementState = {}
+
+  if (checked !== null) state.checked = checked
+  if (selectedFlag !== null) {
+    state.selected = textValue || node['@_content-desc'] || true
+  }
+  if (focused !== null) state.focused = focused
+  if (expanded !== null) state.expanded = expanded
+  if (enabled !== null) state.enabled = enabled
+
+  if (textValue && /edittext|textfield|search/i.test(String(node['@_class'] || ''))) {
+    state.text_value = textValue
+  }
+
+  addNumericState(node, state, textValue)
+
+  return Object.keys(state).length > 0 ? state : null
+}
+
+export function traverseNode(node: AndroidXMLNode, elements: UIElement[], parentIndex: number = -1, depth: number = 0): number {
+  if (!node) return -1;
+
+  let currentIndex = -1;
+
+  if (node['@_class']) {
+    const { text, contentDescription, clickable, className, bounds, state, role, resourceId, stableId, testTag, selector, semantic, isUseful } = describeNode(node)
+
+    if (isUseful) {
+      const element: UIElement = {
+        text,
+        contentDescription,
+        type: className,
+        resourceId,
+        clickable,
+        enabled: node['@_enabled'] === 'true',
+        visible: true,
+        bounds,
+        center: getCenter(bounds),
+        depth,
+        state,
+        stable_id: stableId,
+        role,
+        test_tag: testTag,
+        selector,
+        semantic
+      };
+
+      if (parentIndex !== -1) {
+        element.parentId = parentIndex;
+      }
+
+      elements.push(element);
+      currentIndex = elements.length - 1;
+    }
+  }
+
+  const nextParentIndex = currentIndex !== -1 ? currentIndex : parentIndex;
+  const nextDepth = currentIndex !== -1 ? depth + 1 : depth;
+
+  const childrenIndices: number[] = [];
+
+  if (node.node) {
+    if (Array.isArray(node.node)) {
+      node.node.forEach((child: AndroidXMLNode) => {
+        const childIndex = traverseNode(child, elements, nextParentIndex, nextDepth);
+        if (childIndex !== -1) childrenIndices.push(childIndex);
+      });
+    } else {
+      const childIndex = traverseNode(node.node, elements, nextParentIndex, nextDepth);
+      if (childIndex !== -1) childrenIndices.push(childIndex);
+    }
+  }
+
+  if (currentIndex !== -1 && childrenIndices.length > 0) {
+    elements[currentIndex].children = childrenIndices;
+  }
+
+  return currentIndex;
+}
+
+function addNumericState(node: AndroidXMLNode, state: UIElementState, textValue: string | null) {
+  if (isSliderLikeAndroid(node)) {
+    const rawProgress = parseNumberAttr(node['@_progress'])
+    const max = parseNumberAttr(node['@_max'])
+    const fallbackValue = rawProgress ?? parseNumberAttr(node['@_value']) ?? parseNumberAttr(node['@_content-desc'])
+    const numericValue = rawProgress ?? fallbackValue
+    if (numericValue !== null) {
+      state.raw_value = numericValue
+      state.value_range = max !== null && max > 0 ? { min: 0, max } : null
+      state.value = max !== null && max > 0 ? Math.round((numericValue / max) * 100) : numericValue
+    }
+  } else {
+    const numericValue = parseNumberAttr(node['@_value'])
+    if (numericValue !== null) {
+      state.value = numericValue
+      state.raw_value = numericValue
+    } else if (textValue) {
+      state.value = textValue
+    }
+  }
+
+}
+
+function describeNode(node: AndroidXMLNode) {
+  const text = node['@_text'] || null;
+  const contentDescription = node['@_content-desc'] || null;
+  const clickable = node['@_clickable'] === 'true';
+  const className = String(node['@_class'] || 'unknown');
+  const bounds = parseBounds(node['@_bounds'] || '[0,0][0,0]');
+  const state = extractAndroidState(node);
+  const role = inferAndroidRole(normalizeClassName(className));
+  const resourceId = typeof node['@_resource-id'] === 'string' && node['@_resource-id'].trim().length > 0 ? node['@_resource-id'] : null
+  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), role)
+
+  const isUseful = clickable || (text && text.length > 0) || (contentDescription && contentDescription.length > 0);
+
+  return { text, contentDescription, clickable, className, bounds, state, role, resourceId, stableId, testTag, selector, semantic, isUseful }
+}