mobile-debug-mcp 0.33.0 → 0.35.0

package/dist/observe/ios/log-stream.js

@@ -0,0 +1,105 @@
+import { captureEvidence } from '../evidence.js';
+import { spawn } from "child_process";
+import { getXcrunCmd } from "../../utils/ios/utils.js";
+import { createWriteStream, promises as fsPromises } from 'fs';
+import path from 'path';
+import { parseLogLine } from '../../utils/android/utils.js';
+import { iosActiveLogStreams } from './context.js';
+export async function startLogStream(bundleId, deviceId = 'booted', sessionId = 'default') {
+    try {
+        const simple = bundleId.split('.').pop() || bundleId;
+        const predicate = `process == "${simple}" or process == "${bundleId}" or subsystem contains "${bundleId}"`;
+        if (iosActiveLogStreams.has(sessionId)) {
+            try {
+                iosActiveLogStreams.get(sessionId).proc.kill();
+            }
+            catch { }
+            iosActiveLogStreams.delete(sessionId);
+        }
+        const args = ['simctl', 'spawn', deviceId, 'log', 'stream', '--style', 'syslog', '--predicate', predicate];
+        const proc = spawn(getXcrunCmd(), args);
+        const tmpDir = process.env.TMPDIR || '/tmp';
+        const file = path.join(tmpDir, `mobile-debug-ios-log-${sessionId}.ndjson`);
+        const stream = createWriteStream(file, { flags: 'a' });
+        proc.stdout.on('data', (chunk) => {
+            const text = chunk.toString();
+            const lines = text.split(/\r?\n/).filter(Boolean);
+            for (const l of lines) {
+                const entry = parseLogLine(l);
+                stream.write(JSON.stringify(entry) + '\n');
+            }
+        });
+        proc.stderr.on('data', (chunk) => {
+            const text = chunk.toString();
+            const lines = text.split(/\r?\n/).filter(Boolean);
+            for (const l of lines) {
+                const entry = { timestamp: '', level: 'E', tag: 'xcrun', message: l };
+                stream.write(JSON.stringify(entry) + '\n');
+            }
+        });
+        proc.on('close', () => {
+            stream.end();
+            if (iosActiveLogStreams.get(sessionId)?.proc === proc)
+                iosActiveLogStreams.delete(sessionId);
+        });
+        iosActiveLogStreams.set(sessionId, { proc, file, device: { platform: 'ios', id: deviceId ?? '' } });
+        return { success: true, stream_started: true };
+    }
+    catch {
+        return { success: false, error: 'log_stream_start_failed' };
+    }
+}
+export async function stopLogStream(sessionId = 'default') {
+    const entry = iosActiveLogStreams.get(sessionId);
+    if (!entry)
+        return { success: true };
+    try {
+        entry.proc.kill();
+    }
+    catch { }
+    iosActiveLogStreams.delete(sessionId);
+    return { success: true };
+}
+export async function readLogStream(sessionId = 'default', limit = 100, since) {
+    return captureEvidence('logs', iosActiveLogStreams.get(sessionId)?.device ?? null, () => collectReadLogStream(sessionId, limit, since));
+}
+export async function collectReadLogStream(sessionId = 'default', limit = 100, since) {
+    const entry = iosActiveLogStreams.get(sessionId);
+    if (!entry)
+        return { entries: [] };
+    try {
+        const data = await fsPromises.readFile(entry.file, 'utf8').catch(() => '');
+        if (!data)
+            return { entries: [], crash_summary: { crash_detected: false } };
+        const lines = data.split(/\r?\n/).filter(Boolean);
+        const parsed = lines.map(l => {
+            try {
+                return JSON.parse(l);
+            }
+            catch {
+                return { message: l, _iso: null, crash: false };
+            }
+        });
+        let filtered = parsed;
+        if (since) {
+            let sinceMs = null;
+            if (/^\d+$/.test(since))
+                sinceMs = Number(since);
+            else {
+                const sDate = new Date(since);
+                if (!isNaN(sDate.getTime()))
+                    sinceMs = sDate.getTime();
+            }
+            if (sinceMs !== null) {
+                filtered = parsed.filter(p => p._iso && (new Date(p._iso).getTime() >= sinceMs));
+            }
+        }
+        const entries = filtered.slice(-Math.max(0, limit));
+        const crashEntry = entries.find(e => e.crash);
+        const crash_summary = crashEntry ? { crash_detected: true, exception: crashEntry.exception, sample: crashEntry.message } : { crash_detected: false };
+        return { entries, crash_summary };
+    }
+    catch {
+        return { entries: [], crash_summary: { crash_detected: false } };
+    }
+}

package/dist/observe/ios/logs.js

@@ -0,0 +1,168 @@
+import { getIOSDeviceMetadata, validateBundleId } from "../../utils/ios/utils.js";
+import { iosExecCommand } from './context.js';
+export async function collectGetLogs(filters = {}) {
+    const { appId, deviceId = 'booted', pid, tag, level, contains, since_seconds, limit } = filters;
+    const effectiveLimit = typeof limit === 'number' && limit > 0 ? limit : 50;
+    const { args, processNameUsed } = logArguments(filters, deviceId);
+    try {
+        const detectedPid = await detectLogPid(appId, pid, deviceId);
+        const effectivePid = pid || detectedPid || null;
+        const result = await iosExecCommand(args, deviceId);
+        const device = await getIOSDeviceMetadata(deviceId);
+        const rawLines = result.output ? result.output.split(/\r?\n/).filter(Boolean) : [];
+        // Parse lines into structured entries. iOS log format: timestamp [PID:tid] <level> subsystem:category: message
+        const parsed = rawLines.map(line => parseIOSLog(line));
+        const filtered = filterLogs(parsed, filters, effectivePid, processNameUsed);
+        // Order oldest -> newest
+        filtered.sort((a, b) => {
+            const ta = a.timestamp ? new Date(a.timestamp).getTime() : 0;
+            const tb = b.timestamp ? new Date(b.timestamp).getTime() : 0;
+            return ta - tb;
+        });
+        const source = effectivePid ? 'pid' : (appId ? 'process' : 'broad');
+        const meta = { appIdProvided: !!appId, processNameUsed: processNameUsed || null, detectedPid: detectedPid || null, filters: { tag, level, contains, since_seconds, limit: effectiveLimit }, pidExplicit: !!pid };
+        const limited = filtered.slice(-Math.max(0, effectiveLimit));
+        return { device, logs: limited, logCount: limited.length, source, meta };
+    }
+    catch (err) {
+        console.error('iOS getLogs failed:', err);
+        const device = await getIOSDeviceMetadata(deviceId);
+        return { device, logs: [], logCount: 0, source: 'broad', meta: { error: err instanceof Error ? err.message : String(err) } };
+    }
+}
+function parseIOSLog(line) {
+    // Example: 2023-08-12 12:34:56.789012+0000  pid  <Debug>  MyApp[123:456]  <info>  MySubsystem: MyCategory: Message here
+    // Simpler approach: try to extract ISO timestamp at start
+    let ts = null;
+    const tsMatch = line.match(/^(\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2}:\d{2}(?:\.\d+)?)/);
+    if (tsMatch) {
+        const d = new Date(tsMatch[1]);
+        if (!isNaN(d.getTime()))
+            ts = d.toISOString();
+    }
+    // level mapping
+    let lvl = 'INFO';
+    const lvlMatch = line.match(/\b(Debug|Info|Default|Error|Fault|Warning)\b/i);
+    if (lvlMatch) {
+        const map = { 'debug': 'DEBUG', 'info': 'INFO', 'default': 'DEBUG', 'error': 'ERROR', 'fault': 'ERROR', 'warning': 'WARN' };
+        lvl = map[(lvlMatch[1] || '').toLowerCase()] || 'INFO';
+    }
+    // subsystem/category -> tag
+    let tagVal = '';
+    const tagMatch = line.match(/\s([A-Za-z0-9_./-]+):\s/);
+    if (tagMatch)
+        tagVal = tagMatch[1];
+    // pid extraction
+    let pidNum = null;
+    const pidMatch = line.match(/\[(\d+):\d+\]/);
+    if (pidMatch)
+        pidNum = Number(pidMatch[1]);
+    // message: extract robustly after the subsystem/category token when available
+    let message = line;
+    if (tagMatch) {
+        // tagMatch[0] includes the delimiter (e.g. " MySubsystem: ") — use it to find the message start
+        const marker = tagMatch[0];
+        const idx = line.indexOf(marker);
+        if (idx !== -1) {
+            message = line.slice(idx + marker.length).trim();
+        }
+        else {
+            // fallback: try to trim off common prefixes (timestamp, pid, level) and keep the rest
+            const afterPidMatch = line.match(/\]\s+/);
+            if (afterPidMatch) {
+                const afterPidIdx = line.indexOf(afterPidMatch[0]) + afterPidMatch[0].length;
+                message = line.slice(afterPidIdx).trim();
+            }
+            else {
+                // remove leading level tokens like <Debug> and keep remainder
+                message = line.replace(/^.*?<.*?>\s*/, '').trim();
+            }
+        }
+    }
+    else {
+        // No tag found — strip obvious prefixes and keep remainder (preserve colons in message)
+        message = line.replace(/^.*?<.*?>\s*/, '').trim();
+    }
+    return { timestamp: ts, level: lvl, tag: tagVal, pid: pidNum, message };
+}
+function logArguments(filters, deviceId) {
+    const { appId, tag, since_seconds } = filters;
+    const args = ['simctl', 'spawn', deviceId, 'log', 'show', '--style', 'syslog'];
+    // Default to last N seconds if no since_seconds provided; limit lines handled after parsing
+    if (since_seconds) {
+        // log show accepts --last <time>
+        args.push('--last', `${since_seconds}s`);
+    }
+    else {
+        // default to last 60s to keep quick
+        args.push('--last', '60s');
+    }
+    let processNameUsed = undefined;
+    if (appId) {
+        validateBundleId(appId);
+        // prefer matching the simple process name (last segment of bundle id), but also match full bundle id in subsystem
+        const parts = appId.split('.');
+        const simpleName = parts[parts.length - 1];
+        processNameUsed = simpleName;
+        // predicate: match process by simple name or full bundle id, or subsystem contains bundle id
+        args.push('--predicate', `process == "${simpleName}" or process == "${appId}" or subsystem contains "${appId}"`);
+    }
+    else if (tag) {
+        // predicate by subsystem/category
+        args.push('--predicate', `subsystem contains "${tag}"`);
+    }
+    return { args, processNameUsed };
+}
+async function detectLogPid(appId, pid, deviceId) {
+    // Attempt pid detection if appId provided and no explicit pid supplied — prefer process name derived from bundle id
+    let detectedPid = null;
+    if (appId && !pid) {
+        const parts = appId.split('.');
+        const simpleName = parts[parts.length - 1];
+        try {
+            const pgrepRes = await iosExecCommand(['simctl', 'spawn', deviceId, 'pgrep', '-f', simpleName], deviceId);
+            const out = pgrepRes && pgrepRes.output ? pgrepRes.output.trim() : '';
+            const firstLine = out.split(/\r?\n/).find(Boolean);
+            if (firstLine) {
+                const n = Number(firstLine.trim());
+                if (!isNaN(n) && n > 0)
+                    detectedPid = n;
+            }
+        }
+        catch {
+            // ignore pgrep failures — we'll fall back to process/bundle matching
+        }
+    }
+    return detectedPid;
+}
+function filterLogs(parsed, filters, effectivePid, processNameUsed) {
+    const { contains, since_seconds, level, tag, appId } = filters;
+    // Apply contains filter
+    let filtered = parsed;
+    if (contains)
+        filtered = filtered.filter(e => e.message && e.message.includes(contains));
+    // Apply since_seconds already applied by log show, but double-check timestamps
+    if (since_seconds) {
+        const sinceMs = Date.now() - (since_seconds * 1000);
+        filtered = filtered.filter(e => e.timestamp && (new Date(e.timestamp).getTime() >= sinceMs));
+    }
+    // level filter
+    if (level) {
+        const L = level.toUpperCase();
+        filtered = filtered.filter(e => e.level && e.level.toUpperCase() === L);
+    }
+    // tag filter
+    if (tag)
+        filtered = filtered.filter(e => e.tag && e.tag.includes(tag));
+    // pid filter (use detected/effective pid if available)
+    const pidToFilter = effectivePid;
+    if (pidToFilter)
+        filtered = filtered.filter(e => e.pid === pidToFilter);
+    // If appId present but no predicate returned lines, try substring match
+    if (appId && filtered.length === 0) {
+        const matched = parsed.filter(e => (e.message && e.message.includes(appId)) || (e.tag && e.tag.includes(appId)) || (e.message && processNameUsed && e.message.includes(processNameUsed)));
+        if (matched.length > 0)
+            filtered = matched;
+    }
+    return filtered;
+}

package/dist/observe/ios/screenshot.js

@@ -0,0 +1,22 @@
+import { encodeScreenshot } from '../screenshot-encoding.js';
+import { randomUUID } from 'node:crypto';
+import { promises as fs } from "fs";
+import { getIOSDeviceMetadata } from "../../utils/ios/utils.js";
+import { parsePngSize } from '../../utils/image.js';
+import { iosExecCommand } from './context.js';
+export async function collectCaptureScreenshot(deviceId = "booted") {
+    const device = await getIOSDeviceMetadata(deviceId);
+    const tmpFile = `/tmp/mcp-ios-screenshot-${randomUUID()}.png`;
+    try {
+        await iosExecCommand(['simctl', 'io', deviceId, 'screenshot', tmpFile], deviceId);
+        const buffer = await fs.readFile(tmpFile);
+        const dims = parsePngSize(buffer);
+        const encoded = await encodeScreenshot(buffer, 'ios');
+        await fs.rm(tmpFile).catch(() => { });
+        return { device, ...encoded, resolution: { width: dims.width, height: dims.height } };
+    }
+    catch (e) {
+        await fs.rm(tmpFile).catch(() => { });
+        throw new Error(`Failed to capture screenshot: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}

package/dist/observe/ios/ui-elements.js

@@ -0,0 +1,241 @@
+export function parseIDBFrame(frame) {
+    if (!frame)
+        return [0, 0, 0, 0];
+    if (typeof frame === 'string') {
+        const nums = frame.match(/-?\d+(?:\.\d+)?/g);
+        if (!nums || nums.length < 4)
+            return [0, 0, 0, 0];
+        const x = Number(nums[0]);
+        const y = Number(nums[1]);
+        const w = Number(nums[2]);
+        const h = Number(nums[3]);
+        return [Math.round(x), Math.round(y), Math.round(x + w), Math.round(y + h)];
+    }
+    const x = Number(frame.x || 0);
+    const y = Number(frame.y || 0);
+    const w = Number(frame.width || frame.w || 0);
+    const h = Number(frame.height || frame.h || 0);
+    return [Math.round(x), Math.round(y), Math.round(x + w), Math.round(y + h)];
+}
+export function getCenter(bounds) {
+    const [x1, y1, x2, y2] = bounds;
+    return [Math.floor((x1 + x2) / 2), Math.floor((y1 + y2) / 2)];
+}
+export function parseIOSNumber(value) {
+    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 normalizeIOSType(value) {
+    return typeof value === 'string' ? value.trim().toLowerCase() : '';
+}
+export function inferIOSRole(type, traits) {
+    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';
+    if (/text field|textfield|search field/.test(type))
+        return 'text_field';
+    if (/image/.test(type))
+        return 'image';
+    if (/window|application|group|scroll view|collection view/.test(type))
+        return 'container';
+    return null;
+}
+export function getIOSStableId(node) {
+    const candidates = [node.AXIdentifier, node.accessibilityIdentifier, node.identifier, node.AXUniqueId];
+    for (const candidate of candidates) {
+        if (typeof candidate === 'string' && candidate.trim().length > 0)
+            return candidate;
+    }
+    return null;
+}
+export function buildIOSSelectorConfidence(source) {
+    switch (source) {
+        case 'identifier':
+            return { score: 1, reason: 'accessibility_identifier' };
+        case 'label':
+            return { score: 0.9, reason: 'label_match' };
+        case 'value':
+            return { score: 0.75, reason: 'value_match' };
+        case 'type':
+            return { score: 0.35, reason: 'type_match' };
+        default:
+            return null;
+    }
+}
+export function buildIOSSelector(type, label, value, stableId) {
+    if (stableId)
+        return { value: stableId, confidence: buildIOSSelectorConfidence('identifier') };
+    if (label)
+        return { value: label, confidence: buildIOSSelectorConfidence('label') };
+    if (value)
+        return { value: value, confidence: buildIOSSelectorConfidence('value') };
+    if (type)
+        return { value: type, confidence: buildIOSSelectorConfidence('type') };
+    return null;
+}
+export function buildIOSSemantic(type, traits, role, value) {
+    const semantic = {
+        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;
+}
+export function isIOSAdjustable(node, type, traits) {
+    return /slider|adjustable|stepper/i.test(type) || traits.some((trait) => /adjustable|slider/i.test(trait));
+}
+export function extractIOSState(node, type, label, value, traits) {
+    const state = {};
+    const normalizedTraits = traits.map((trait) => String(trait).toLowerCase());
+    if (normalizedTraits.some((trait) => /selected/.test(trait))) {
+        state.selected = label || value || true;
+    }
+    if (normalizedTraits.some((trait) => /focused/.test(trait))) {
+        state.focused = true;
+    }
+    if (normalizedTraits.some((trait) => /enabled/.test(trait))) {
+        state.enabled = true;
+    }
+    if (normalizedTraits.some((trait) => /disabled/.test(trait))) {
+        state.enabled = false;
+    }
+    if (value && /textfield|search|text/i.test(type)) {
+        state.text_value = value;
+    }
+    if (isIOSAdjustable(node, type, traits)) {
+        const rawValue = parseIOSNumber(value);
+        if (rawValue !== null) {
+            state.raw_value = rawValue;
+            state.value = rawValue >= 0 && rawValue <= 1 ? Math.round(rawValue * 100) : rawValue;
+        }
+        else if (value) {
+            state.raw_value = value;
+            state.value = value;
+        }
+    }
+    else if (value) {
+        const numericValue = parseIOSNumber(value);
+        if (numericValue !== null) {
+            state.value = numericValue;
+            state.raw_value = numericValue;
+        }
+        else {
+            state.value = value;
+        }
+    }
+    return Object.keys(state).length > 0 ? state : null;
+}
+export function traverseIDBNode(node, elements, parentIndex = -1, depth = 0) {
+    if (!node)
+        return -1;
+    let currentIndex = -1;
+    const { type, label, value, frame, state, stableId, selector, role, semantic, clickable, isUseful } = describeIDBNode(node);
+    if (isUseful) {
+        const bounds = parseIDBFrame(frame);
+        const element = {
+            text: label,
+            contentDescription: value,
+            type: type,
+            resourceId: stableId,
+            clickable: clickable,
+            enabled: true,
+            visible: true,
+            bounds: bounds,
+            center: getCenter(bounds),
+            depth: depth,
+            state,
+            stable_id: stableId,
+            role,
+            test_tag: stableId,
+            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 = [];
+    if (node.children && Array.isArray(node.children)) {
+        for (const child of node.children) {
+            const childIndex = traverseIDBNode(child, elements, nextParentIndex, nextDepth);
+            if (childIndex !== -1) {
+                childrenIndices.push(childIndex);
+            }
+        }
+    }
+    if (currentIndex !== -1 && childrenIndices.length > 0) {
+        elements[currentIndex].children = childrenIndices;
+    }
+    return currentIndex;
+}
+function describeIDBNode(node) {
+    const type = node.AXElementType || node.type || "unknown";
+    const label = node.AXLabel || node.label || null;
+    const value = node.AXValue || null;
+    const frame = node.AXFrame || node.frame;
+    const traits = node.AXTraits || [];
+    const state = extractIOSState(node, type, label, value, traits);
+    const normalizedType = normalizeIOSType(type);
+    const stableId = getIOSStableId(node);
+    const selector = buildIOSSelector(type, label, value, stableId);
+    const role = inferIOSRole(normalizedType, traits);
+    const semantic = buildIOSSemantic(normalizedType, traits, role, value);
+    const clickable = traits.includes("UIAccessibilityTraitButton") || type === "Button" || type === "Cell";
+    const isUseful = clickable || (label && label.length > 0) || (value && value.length > 0) || type === "Application" || type === "Window";
+    return { type, label, value, frame, state, stableId, selector, role, semantic, clickable, isUseful };
+}

package/dist/observe/ios/ui-tree.js

@@ -0,0 +1,137 @@
+import { remainingBudget } from '../../utils/operation-budget.js';
+import { execCmd } from '../../utils/exec.js';
+import { createObservationMeasurement } from '../performance-metrics.js';
+import { getIOSDeviceMetadata, getIdbCmd, isIDBInstalled } from "../../utils/ios/utils.js";
+import { deriveSnapshotMetadata } from '../snapshot-metadata.js';
+import { delay } from './context.js';
+import { traverseIDBNode } from './ui-elements.js';
+export async function collectGetUITree(deviceId = "booted") {
+    const measurement = createObservationMeasurement('ios');
+    let device;
+    try {
+        device = await measurement.timed('metadata_ms', () => getIOSDeviceMetadata(deviceId));
+    }
+    catch (error) {
+        measurement.setOutcome('unavailable');
+        measurement.finish();
+        throw error;
+    }
+    const deviceKey = `ios:${device.id}`;
+    const idbExists = await measurement.timed('capability_check_ms', () => isIDBInstalled());
+    if (!idbExists) {
+        const snapshotMetadata = deriveSnapshotMetadata(deviceKey, null, 'ui_tree');
+        measurement.setOutcome('unavailable');
+        measurement.finish();
+        return missingIDBResponse(device, snapshotMetadata);
+    }
+    const targetUdid = (device.id && device.id !== 'booted') ? device.id : undefined;
+    const acquisition = await readIOSTree(targetUdid, measurement);
+    if (!acquisition.success) {
+        const snapshotMetadata = deriveSnapshotMetadata(deviceKey, null, 'ui_tree');
+        measurement.setOutcome('unavailable');
+        measurement.finish();
+        return {
+            device, screen: '', resolution: { width: 0, height: 0 }, elements: [], ...snapshotMetadata,
+            error: 'Failed to retrieve valid UI dump after 3 attempts.'
+        };
+    }
+    const jsonContent = acquisition.tree;
+    try {
+        const elements = await measurement.timed('conversion_ms', async () => {
+            const parsed = [];
+            if (Array.isArray(jsonContent)) {
+                for (const node of jsonContent)
+                    traverseIDBNode(node, parsed);
+            }
+            else {
+                traverseIDBNode(jsonContent, parsed);
+            }
+            return parsed;
+        });
+        let width = 0;
+        let height = 0;
+        if (elements.length > 0) {
+            const rootBounds = elements[0].bounds;
+            width = rootBounds[2] - rootBounds[0];
+            height = rootBounds[3] - rootBounds[1];
+        }
+        const snapshotMetadata = deriveSnapshotMetadata(deviceKey, {
+            screen: "",
+            resolution: { width, height },
+            elements
+        }, 'ui_tree');
+        measurement.setOutcome('observed');
+        const response = measurement.bindObservation({
+            device,
+            screen: "",
+            resolution: { width, height },
+            elements,
+            ...snapshotMetadata
+        });
+        measurement.finish();
+        return response;
+    }
+    catch (e) {
+        const snapshotMetadata = deriveSnapshotMetadata(deviceKey, null, 'ui_tree');
+        measurement.setOutcome('unavailable');
+        measurement.finish();
+        return {
+            device,
+            screen: "",
+            resolution: { width: 0, height: 0 },
+            elements: [],
+            ...snapshotMetadata,
+            error: `Failed to parse idb output: ${e instanceof Error ? e.message : String(e)}`
+        };
+    }
+}
+async function readIOSTree(targetUdid, measurement) {
+    let jsonContent = null;
+    let attempts = 0;
+    const maxAttempts = 3;
+    while (attempts < maxAttempts) {
+        remainingBudget();
+        attempts++;
+        try {
+            await measurement.timed('observation_wait_ms', () => delay(Math.min(remainingBudget(300 + (attempts * 100)), 300 + (attempts * 100))));
+            remainingBudget();
+            const args = ['ui', 'describe-all', '--json'];
+            if (targetUdid) {
+                args.push('--udid', targetUdid);
+            }
+            const output = await measurement.physicalRead(async () => {
+                const result = await execCmd(getIdbCmd(), args, { timeout: remainingBudget() });
+                if (result.stderr === 'ACTION_TIMEOUT')
+                    throw new Error('ACTION_TIMEOUT');
+                if (result.exitCode !== 0)
+                    throw new Error(`idb failed (code ${result.exitCode}): ${result.stderr}`);
+                if (!result.stdout.trim())
+                    throw new Error('Empty idb UI tree output');
+                return result.stdout;
+            });
+            if (output && output.trim().length > 0) {
+                jsonContent = await measurement.timed('parse_ms', async () => JSON.parse(output));
+                break; // Success
+            }
+        }
+        catch (e) {
+            if (e instanceof Error && e.message === 'ACTION_TIMEOUT')
+                throw e;
+            console.error(`Attempt ${attempts} failed: ${e}`);
+        }
+        if (attempts === maxAttempts) {
+            return { success: false, tree: null };
+        }
+    }
+    return { success: true, tree: jsonContent };
+}
+function missingIDBResponse(device, snapshotMetadata) {
+    return {
+        device,
+        screen: "",
+        resolution: { width: 0, height: 0 },
+        elements: [],
+        ...snapshotMetadata,
+        error: "iOS UI tree retrieval requires 'idb' (iOS Device Bridge). Please install it via Homebrew: `brew tap facebook/fb && brew install idb-companion` and `pip3 install fb-idb`."
+    };
+}