@ph-qa/midscene-android 1.6.1

package/dist/es/index.mjs

@@ -0,0 +1,2146 @@
+import * as __rspack_external__midscene_shared_logger_b1dc2426 from "@midscene/shared/logger";
+import * as __rspack_external_node_fs_5ea92f0c from "node:fs";
+import * as __rspack_external_node_module_ab9f2194 from "node:module";
+import * as __rspack_external_node_path_c5b9b54f from "node:path";
+import node_assert from "node:assert";
+import { execFile } from "node:child_process";
+import { request } from "node:http";
+import { createServer } from "node:net";
+import { getMidsceneLocationSchema, z } from "@midscene/core";
+import { defineAction, defineActionClearInput, defineActionCursorMove, defineActionDoubleClick, defineActionDragAndDrop, defineActionKeyboardPress, defineActionPinch, defineActionScroll, defineActionSwipe, defineActionTap, normalizeMobileSwipeParam, normalizePinchParam } from "@midscene/core/device";
+import { getTmpFile, sleep } from "@midscene/core/utils";
+import { MIDSCENE_ADB_PATH, MIDSCENE_ADB_REMOTE_HOST, MIDSCENE_ADB_REMOTE_PORT, MIDSCENE_ANDROID_IME_STRATEGY, globalConfigManager, overrideAIConfig } from "@midscene/shared/env";
+import { createImgBase64ByFormat, isValidImageBuffer } from "@midscene/shared/img";
+import { mergeAndNormalizeAppNameMapping, normalizeForComparison, repeat } from "@midscene/shared/utils";
+import { ADB } from "appium-adb";
+import { Agent } from "@midscene/core/agent";
+import { BaseMidsceneTools } from "@midscene/shared/mcp";
+var __webpack_modules__ = {
+    "./src/scrcpy-manager.ts" (__unused_rspack_module, __webpack_exports__, __webpack_require__) {
+        __webpack_require__.d(__webpack_exports__, {
+            ScrcpyScreenshotManager: ()=>ScrcpyScreenshotManager,
+            o: ()=>DEFAULT_SCRCPY_CONFIG
+        });
+        var node_fs__rspack_import_0 = __webpack_require__("node:fs");
+        var node_module__rspack_import_1 = __webpack_require__("node:module");
+        var node_path__rspack_import_2 = __webpack_require__("node:path");
+        var _midscene_shared_logger__rspack_import_3 = __webpack_require__("@midscene/shared/logger");
+        function _define_property(obj, key, value) {
+            if (key in obj) Object.defineProperty(obj, key, {
+                value: value,
+                enumerable: true,
+                configurable: true,
+                writable: true
+            });
+            else obj[key] = value;
+            return obj;
+        }
+        const debugScrcpy = (0, _midscene_shared_logger__rspack_import_3.getDebug)('android:scrcpy');
+        const warnScrcpy = (0, _midscene_shared_logger__rspack_import_3.getDebug)('android:scrcpy', {
+            console: true
+        });
+        const NAL_TYPE_IDR = 5;
+        const NAL_TYPE_SPS = 7;
+        const NAL_TYPE_PPS = 8;
+        const NAL_TYPE_MASK = 0x1f;
+        const DEFAULT_MAX_SIZE = 0;
+        const DEFAULT_VIDEO_BIT_RATE = 100000000;
+        const MAX_VIDEO_BIT_RATE = 100000000;
+        const DEFAULT_IDLE_TIMEOUT_MS = 30000;
+        const MAX_KEYFRAME_WAIT_MS = 5000;
+        const FRESH_FRAME_TIMEOUT_MS = 300;
+        const KEYFRAME_POLL_INTERVAL_MS = 200;
+        const MAX_SCAN_BYTES = 1000;
+        const CONNECTION_WAIT_MS = 1000;
+        const BUSY_LOOP_WINDOW_MS = 1000;
+        const BUSY_LOOP_MAX_READS = 500;
+        const BUSY_LOOP_COOLDOWN_MS = 50;
+        const BUSY_LOOP_WARN_INTERVAL_MS = 5000;
+        const DEFAULT_SCRCPY_CONFIG = {
+            enabled: false,
+            maxSize: DEFAULT_MAX_SIZE,
+            idleTimeoutMs: DEFAULT_IDLE_TIMEOUT_MS,
+            videoBitRate: DEFAULT_VIDEO_BIT_RATE
+        };
+        function isKeyFrameNalType(nalUnitType) {
+            return nalUnitType === NAL_TYPE_IDR || nalUnitType === NAL_TYPE_SPS || nalUnitType === NAL_TYPE_PPS;
+        }
+        function detectH264KeyFrame(buffer) {
+            const scanLimit = Math.min(buffer.length - 4, MAX_SCAN_BYTES);
+            for(let i = 0; i < scanLimit; i++)if (0x00 === buffer[i] && 0x00 === buffer[i + 1] && 0x00 === buffer[i + 2] && 0x01 === buffer[i + 3]) {
+                const nalUnitType = buffer[i + 4] & NAL_TYPE_MASK;
+                if (isKeyFrameNalType(nalUnitType)) return true;
+            } else if (0x00 === buffer[i] && 0x00 === buffer[i + 1] && 0x01 === buffer[i + 2]) {
+                const nalUnitType = buffer[i + 3] & NAL_TYPE_MASK;
+                if (isKeyFrameNalType(nalUnitType)) return true;
+            }
+            return false;
+        }
+        class ScrcpyScreenshotManager {
+            async validateEnvironment() {
+                await this.ensureFfmpegAvailable();
+            }
+            async ensureConnected() {
+                if (this.scrcpyClient && this.videoStream) {
+                    debugScrcpy('Scrcpy already connected');
+                    this.resetIdleTimer();
+                    return;
+                }
+                if (this.isConnecting) {
+                    debugScrcpy('Connection already in progress, waiting...');
+                    await new Promise((resolve)=>setTimeout(resolve, CONNECTION_WAIT_MS));
+                    if (this.scrcpyClient && this.videoStream) return void this.resetIdleTimer();
+                    throw new Error('Scrcpy connection failed: another connection attempt did not complete in time');
+                }
+                try {
+                    this.isConnecting = true;
+                    debugScrcpy('Starting scrcpy connection...');
+                    const { AdbScrcpyClient, AdbScrcpyOptions3_3_3 } = await import("@yume-chan/adb-scrcpy");
+                    const { ReadableStream } = await import("@yume-chan/stream-extra");
+                    const { DefaultServerPath } = await import("@yume-chan/scrcpy");
+                    const serverBinPath = this.resolveServerBinPath();
+                    await AdbScrcpyClient.pushServer(this.adb, ReadableStream.from((0, node_fs__rspack_import_0.createReadStream)(serverBinPath)));
+                    const scrcpyOptions = new AdbScrcpyOptions3_3_3({
+                        audio: false,
+                        control: false,
+                        maxSize: this.options.maxSize,
+                        videoBitRate: this.options.videoBitRate,
+                        maxFps: 10,
+                        sendFrameMeta: true,
+                        videoCodecOptions: 'i-frame-interval=0,bitrate-mode=2'
+                    });
+                    this.scrcpyClient = await AdbScrcpyClient.start(this.adb, DefaultServerPath, scrcpyOptions);
+                    const videoStreamPromise = this.scrcpyClient.videoStream;
+                    if (!videoStreamPromise) throw new Error('Scrcpy client did not provide video stream');
+                    this.videoStream = await videoStreamPromise;
+                    const { width = 0, height = 0 } = this.videoStream.metadata;
+                    debugScrcpy(`Video stream started: ${width}x${height}`);
+                    this.videoResolution = {
+                        width,
+                        height
+                    };
+                    this.startFrameConsumer();
+                    this.resetIdleTimer();
+                    this.isInitialized = true;
+                    debugScrcpy('Scrcpy connection established');
+                } catch (error) {
+                    debugScrcpy(`Failed to connect scrcpy: ${error}`);
+                    await this.disconnect();
+                    throw error;
+                } finally{
+                    this.isConnecting = false;
+                }
+            }
+            resolveServerBinPath() {
+                const androidPkgJson = (0, node_module__rspack_import_1.createRequire)(import.meta.url).resolve('@midscene/android/package.json');
+                return node_path__rspack_import_2["default"].join(node_path__rspack_import_2["default"].dirname(androidPkgJson), 'bin', 'scrcpy-server');
+            }
+            getFfmpegPath() {
+                try {
+                    const dynamicRequire = (0, node_module__rspack_import_1.createRequire)(import.meta.url);
+                    const ffmpegInstaller = dynamicRequire('@ffmpeg-installer/ffmpeg');
+                    debugScrcpy(`Using ffmpeg from npm package: ${ffmpegInstaller.path}`);
+                    return ffmpegInstaller.path;
+                } catch (error) {
+                    debugScrcpy('Using system ffmpeg (npm package not found)');
+                    return 'ffmpeg';
+                }
+            }
+            startFrameConsumer() {
+                if (!this.videoStream) return;
+                const reader = this.videoStream.stream.getReader();
+                this.streamReader = reader;
+                this.consumeFramesLoop(reader);
+            }
+            async consumeFramesLoop(reader) {
+                let readCount = 0;
+                let windowStart = Date.now();
+                let lastBusyWarn = 0;
+                let totalReads = 0;
+                try {
+                    while(true){
+                        const { done, value } = await reader.read();
+                        if (done) break;
+                        totalReads++;
+                        readCount++;
+                        const now = Date.now();
+                        const elapsed = now - windowStart;
+                        if (elapsed >= BUSY_LOOP_WINDOW_MS) {
+                            const readsPerSec = readCount / elapsed * 1000;
+                            if (readCount > BUSY_LOOP_MAX_READS) {
+                                if (now - lastBusyWarn >= BUSY_LOOP_WARN_INTERVAL_MS) {
+                                    warnScrcpy(`[CPU-DIAG] Possible busy loop detected! ${readCount} reads in ${elapsed}ms (${readsPerSec.toFixed(0)} reads/sec). Total reads: ${totalReads}. Throttling with ${BUSY_LOOP_COOLDOWN_MS}ms delay.`);
+                                    lastBusyWarn = now;
+                                }
+                                await new Promise((resolve)=>setTimeout(resolve, BUSY_LOOP_COOLDOWN_MS));
+                            } else debugScrcpy(`[CPU-DIAG] Frame loop stats: ${readCount} reads in ${elapsed}ms (${readsPerSec.toFixed(1)} reads/sec), total: ${totalReads}`);
+                            readCount = 0;
+                            windowStart = Date.now();
+                        }
+                        this.processFrame(value);
+                    }
+                } catch (error) {
+                    debugScrcpy(`Frame consumer error (total reads: ${totalReads}): ${error}`);
+                    await this.disconnect();
+                }
+                debugScrcpy(`Frame consumer loop ended normally (total reads: ${totalReads})`);
+            }
+            processFrame(packet) {
+                if ('configuration' === packet.type) {
+                    this.spsHeader = Buffer.from(packet.data);
+                    debugScrcpy(`Received SPS/PPS configuration: ${this.spsHeader.length}B`);
+                    return;
+                }
+                const frameBuffer = Buffer.from(packet.data);
+                const isKeyFrame = detectH264KeyFrame(frameBuffer);
+                if (isKeyFrame && this.spsHeader) {
+                    this.lastRawKeyframe = frameBuffer;
+                    if (this.keyframeResolvers.length > 0) {
+                        const combined = Buffer.concat([
+                            this.spsHeader,
+                            frameBuffer
+                        ]);
+                        this.notifyKeyframeWaiters(combined);
+                    }
+                }
+            }
+            async getScreenshotJpeg() {
+                const perfStart = Date.now();
+                const t1 = Date.now();
+                await this.ensureConnected();
+                const connectTime = Date.now() - t1;
+                const t2 = Date.now();
+                await this.waitForKeyframe();
+                const spsWaitTime = Date.now() - t2;
+                const t3 = Date.now();
+                let keyframeBuffer;
+                let frameSource;
+                try {
+                    keyframeBuffer = await this.waitForNextKeyframe(FRESH_FRAME_TIMEOUT_MS);
+                    frameSource = 'fresh';
+                } catch  {
+                    if (this.lastRawKeyframe && this.spsHeader) {
+                        keyframeBuffer = Buffer.concat([
+                            this.spsHeader,
+                            this.lastRawKeyframe
+                        ]);
+                        frameSource = 'cached';
+                    } else {
+                        keyframeBuffer = await this.waitForNextKeyframe(MAX_KEYFRAME_WAIT_MS);
+                        frameSource = 'fresh-retry';
+                    }
+                }
+                const frameWaitTime = Date.now() - t3;
+                this.resetIdleTimer();
+                debugScrcpy(`Decoding H.264 stream: ${keyframeBuffer.length} bytes (${frameSource})`);
+                const t4 = Date.now();
+                const result = await this.decodeH264ToJpeg(keyframeBuffer);
+                const decodeTime = Date.now() - t4;
+                const totalTime = Date.now() - perfStart;
+                debugScrcpy(`Performance: total=${totalTime}ms (connect=${connectTime}ms, spsWait=${spsWaitTime}ms, frameWait=${frameWaitTime}ms[${frameSource}], decode=${decodeTime}ms)`);
+                return result;
+            }
+            getResolution() {
+                return this.videoResolution;
+            }
+            notifyKeyframeWaiters(buf) {
+                const resolvers = this.keyframeResolvers;
+                this.keyframeResolvers = [];
+                for (const resolve of resolvers)resolve(buf);
+            }
+            waitForNextKeyframe(timeoutMs) {
+                return new Promise((resolve, reject)=>{
+                    const wrappedResolve = (buf)=>{
+                        clearTimeout(timer);
+                        resolve(buf);
+                    };
+                    const timer = setTimeout(()=>{
+                        this.keyframeResolvers = this.keyframeResolvers.filter((r)=>r !== wrappedResolve);
+                        reject(new Error(`No fresh keyframe received within ${timeoutMs}ms`));
+                    }, timeoutMs);
+                    this.keyframeResolvers.push(wrappedResolve);
+                });
+            }
+            async ensureFfmpegAvailable() {
+                if (null !== this.ffmpegAvailable) return;
+                try {
+                    this.ffmpegAvailable = await this.checkFfmpegAvailable();
+                    if (!this.ffmpegAvailable) debugScrcpy("Warning: ffmpeg is not available. Scrcpy screenshot will be disabled.\nTo enable high-performance screenshots:\n  1. Install optional dependency: pnpm add -D @ffmpeg-installer/ffmpeg\n  2. Or install system ffmpeg: https://ffmpeg.org");
+                } catch (error) {
+                    this.ffmpegAvailable = false;
+                    debugScrcpy(`Error checking ffmpeg availability: ${error}`);
+                }
+                if (!this.ffmpegAvailable) throw new Error('ffmpeg is not available, please use standard ADB screenshot mode');
+            }
+            async waitForKeyframe() {
+                const startTime = Date.now();
+                while(!this.spsHeader && Date.now() - startTime < MAX_KEYFRAME_WAIT_MS){
+                    const elapsed = Date.now() - startTime;
+                    debugScrcpy(`Waiting for first keyframe (SPS/PPS header)... ${elapsed}ms`);
+                    await new Promise((resolve)=>setTimeout(resolve, KEYFRAME_POLL_INTERVAL_MS));
+                }
+                if (!this.spsHeader) throw new Error(`No keyframe received within ${MAX_KEYFRAME_WAIT_MS}ms. Device may have a long GOP interval or video encoding issues. Please retry.`);
+            }
+            async checkFfmpegAvailable() {
+                const { execFile } = await import("node:child_process");
+                const { promisify } = await import("node:util");
+                const execFileAsync = promisify(execFile);
+                try {
+                    const ffmpegPath = this.getFfmpegPath();
+                    await execFileAsync(ffmpegPath, [
+                        '-version'
+                    ]);
+                    debugScrcpy(`ffmpeg is available at: ${ffmpegPath}`);
+                    return true;
+                } catch (error) {
+                    debugScrcpy(`ffmpeg is not available: ${error}`);
+                    return false;
+                }
+            }
+            async decodeH264ToJpeg(h264Buffer) {
+                const { spawn } = await import("node:child_process");
+                return new Promise((resolve, reject)=>{
+                    const ffmpegArgs = [
+                        '-f',
+                        'h264',
+                        '-i',
+                        'pipe:0',
+                        '-vframes',
+                        '1',
+                        '-f',
+                        'image2pipe',
+                        '-vcodec',
+                        'mjpeg',
+                        '-q:v',
+                        '5',
+                        '-loglevel',
+                        'error',
+                        'pipe:1'
+                    ];
+                    const ffmpegPath = this.getFfmpegPath();
+                    const ffmpeg = spawn(ffmpegPath, ffmpegArgs, {
+                        stdio: [
+                            'pipe',
+                            'pipe',
+                            'pipe'
+                        ]
+                    });
+                    const chunks = [];
+                    let stderrOutput = '';
+                    ffmpeg.stdout.on('data', (chunk)=>{
+                        chunks.push(chunk);
+                    });
+                    ffmpeg.stderr.on('data', (data)=>{
+                        stderrOutput += data.toString();
+                    });
+                    ffmpeg.on('close', (code)=>{
+                        if (0 === code && chunks.length > 0) {
+                            const jpegBuffer = Buffer.concat(chunks);
+                            debugScrcpy(`FFmpeg decode successful, JPEG size: ${jpegBuffer.length} bytes`);
+                            resolve(jpegBuffer);
+                        } else {
+                            const errorMsg = stderrOutput || `FFmpeg exited with code ${code}`;
+                            debugScrcpy(`FFmpeg decode failed: ${errorMsg}`);
+                            reject(new Error(`H.264 to JPEG decode failed: ${errorMsg}`));
+                        }
+                    });
+                    ffmpeg.on('error', (error)=>{
+                        reject(new Error(`Failed to spawn ffmpeg process: ${error.message}`));
+                    });
+                    ffmpeg.stdin.write(h264Buffer);
+                    ffmpeg.stdin.end();
+                });
+            }
+            resetIdleTimer() {
+                if (this.idleTimer) clearTimeout(this.idleTimer);
+                if (!this.options.idleTimeoutMs) return;
+                this.idleTimer = setTimeout(()=>{
+                    debugScrcpy('Idle timeout reached, disconnecting scrcpy');
+                    this.disconnect();
+                }, this.options.idleTimeoutMs);
+            }
+            async disconnect() {
+                debugScrcpy('Disconnecting scrcpy...');
+                if (this.idleTimer) {
+                    clearTimeout(this.idleTimer);
+                    this.idleTimer = null;
+                }
+                const client = this.scrcpyClient;
+                const reader = this.streamReader;
+                this.scrcpyClient = null;
+                this.videoStream = null;
+                this.streamReader = null;
+                this.spsHeader = null;
+                this.lastRawKeyframe = null;
+                this.isInitialized = false;
+                this.keyframeResolvers = [];
+                if (reader) try {
+                    reader.cancel();
+                } catch  {}
+                if (client) try {
+                    await client.close();
+                } catch (error) {
+                    debugScrcpy(`Error closing scrcpy client: ${error}`);
+                }
+                debugScrcpy('Scrcpy disconnected');
+            }
+            isConnected() {
+                return this.isInitialized && null !== this.scrcpyClient;
+            }
+            constructor(adb, options = {}){
+                _define_property(this, "adb", void 0);
+                _define_property(this, "scrcpyClient", null);
+                _define_property(this, "videoStream", null);
+                _define_property(this, "spsHeader", null);
+                _define_property(this, "idleTimer", null);
+                _define_property(this, "isConnecting", false);
+                _define_property(this, "isInitialized", false);
+                _define_property(this, "options", void 0);
+                _define_property(this, "ffmpegAvailable", null);
+                _define_property(this, "keyframeResolvers", []);
+                _define_property(this, "lastRawKeyframe", null);
+                _define_property(this, "videoResolution", null);
+                _define_property(this, "streamReader", null);
+                this.adb = adb;
+                const requestedBitRate = options.videoBitRate ?? DEFAULT_VIDEO_BIT_RATE;
+                const clampedBitRate = Math.min(requestedBitRate, MAX_VIDEO_BIT_RATE);
+                if (requestedBitRate > MAX_VIDEO_BIT_RATE) warnScrcpy(`videoBitRate ${requestedBitRate} exceeds maximum ${MAX_VIDEO_BIT_RATE}, clamped to ${clampedBitRate}`);
+                this.options = {
+                    maxSize: options.maxSize ?? DEFAULT_MAX_SIZE,
+                    videoBitRate: clampedBitRate,
+                    idleTimeoutMs: options.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS
+                };
+            }
+        }
+    },
+    "@midscene/shared/logger" (module) {
+        module.exports = __rspack_external__midscene_shared_logger_b1dc2426;
+    },
+    "node:fs" (module) {
+        module.exports = __rspack_external_node_fs_5ea92f0c;
+    },
+    "node:module" (module) {
+        module.exports = __rspack_external_node_module_ab9f2194;
+    },
+    "node:path" (module) {
+        module.exports = __rspack_external_node_path_c5b9b54f;
+    }
+};
+var __webpack_module_cache__ = {};
+function __webpack_require__(moduleId) {
+    var cachedModule = __webpack_module_cache__[moduleId];
+    if (void 0 !== cachedModule) return cachedModule.exports;
+    var module = __webpack_module_cache__[moduleId] = {
+        exports: {}
+    };
+    __webpack_modules__[moduleId](module, module.exports, __webpack_require__);
+    return module.exports;
+}
+(()=>{
+    __webpack_require__.d = (exports, definition)=>{
+        for(var key in definition)if (__webpack_require__.o(definition, key) && !__webpack_require__.o(exports, key)) Object.defineProperty(exports, key, {
+            enumerable: true,
+            get: definition[key]
+        });
+    };
+})();
+(()=>{
+    __webpack_require__.o = (obj, prop)=>Object.prototype.hasOwnProperty.call(obj, prop);
+})();
+var external_node_fs_ = __webpack_require__("node:fs");
+var external_node_module_ = __webpack_require__("node:module");
+var external_node_path_ = __webpack_require__("node:path");
+var logger_ = __webpack_require__("@midscene/shared/logger");
+var scrcpy_manager = __webpack_require__("./src/scrcpy-manager.ts");
+function _define_property(obj, key, value) {
+    if (key in obj) Object.defineProperty(obj, key, {
+        value: value,
+        enumerable: true,
+        configurable: true,
+        writable: true
+    });
+    else obj[key] = value;
+    return obj;
+}
+const debugAdapter = (0, logger_.getDebug)('android:scrcpy-adapter');
+class ScrcpyDeviceAdapter {
+    isEnabled() {
+        if (this.initFailed) return false;
+        return this.scrcpyConfig?.enabled ?? scrcpy_manager.o.enabled;
+    }
+    async initialize(deviceInfo) {
+        try {
+            const manager = await this.ensureManager(deviceInfo);
+            await manager.ensureConnected();
+        } catch (error) {
+            this.initFailed = true;
+            throw error;
+        }
+    }
+    resolveConfig(deviceInfo) {
+        if (this.resolvedConfig) return this.resolvedConfig;
+        const config = this.scrcpyConfig;
+        const maxSize = config?.maxSize ?? scrcpy_manager.o.maxSize;
+        const videoBitRate = config?.videoBitRate ?? scrcpy_manager.o.videoBitRate;
+        this.resolvedConfig = {
+            enabled: this.isEnabled(),
+            maxSize,
+            idleTimeoutMs: config?.idleTimeoutMs ?? scrcpy_manager.o.idleTimeoutMs,
+            videoBitRate
+        };
+        return this.resolvedConfig;
+    }
+    async ensureManager(deviceInfo) {
+        if (this.manager) return this.manager;
+        debugAdapter('Initializing Scrcpy manager...');
+        try {
+            const { Adb, AdbServerClient } = await import("@yume-chan/adb");
+            const { AdbServerNodeTcpConnector } = await import("@yume-chan/adb-server-node-tcp");
+            const { ScrcpyScreenshotManager: ScrcpyManager } = await Promise.resolve().then(__webpack_require__.bind(__webpack_require__, "./src/scrcpy-manager.ts"));
+            const adbClient = new AdbServerClient(new AdbServerNodeTcpConnector({
+                host: '127.0.0.1',
+                port: 5037
+            }));
+            const adb = new Adb(await adbClient.createTransport({
+                serial: this.deviceId
+            }));
+            const config = this.resolveConfig(deviceInfo);
+            const manager = new ScrcpyManager(adb, {
+                maxSize: config.maxSize,
+                videoBitRate: config.videoBitRate,
+                idleTimeoutMs: config.idleTimeoutMs
+            });
+            await manager.validateEnvironment();
+            this.manager = manager;
+            debugAdapter('Scrcpy manager initialized');
+            return this.manager;
+        } catch (error) {
+            debugAdapter(`Failed to initialize Scrcpy manager: ${error}`);
+            throw new Error(`Failed to initialize Scrcpy for device ${this.deviceId}. Ensure ADB server is running and device is connected. Error: ${error}`);
+        }
+    }
+    async screenshotBase64(deviceInfo) {
+        const manager = await this.ensureManager(deviceInfo);
+        const screenshotBuffer = await manager.getScreenshotJpeg();
+        return createImgBase64ByFormat('jpeg', screenshotBuffer.toString('base64'));
+    }
+    getResolution() {
+        return this.manager?.getResolution() ?? null;
+    }
+    getSize(deviceInfo) {
+        const resolution = this.getResolution();
+        if (!resolution) return null;
+        debugAdapter(`Using scrcpy resolution: ${resolution.width}x${resolution.height}`);
+        return {
+            width: resolution.width,
+            height: resolution.height
+        };
+    }
+    getScalingRatio(physicalWidth) {
+        const resolution = this.getResolution();
+        if (!resolution) return null;
+        return resolution.width / physicalWidth;
+    }
+    async disconnect() {
+        if (this.manager) {
+            try {
+                await this.manager.disconnect();
+            } catch (error) {
+                debugAdapter(`Error disconnecting scrcpy: ${error}`);
+            }
+            this.manager = null;
+        }
+        this.resolvedConfig = null;
+    }
+    constructor(deviceId, scrcpyConfig){
+        _define_property(this, "deviceId", void 0);
+        _define_property(this, "scrcpyConfig", void 0);
+        _define_property(this, "manager", void 0);
+        _define_property(this, "resolvedConfig", void 0);
+        _define_property(this, "initFailed", void 0);
+        this.deviceId = deviceId;
+        this.scrcpyConfig = scrcpyConfig;
+        this.manager = null;
+        this.resolvedConfig = null;
+        this.initFailed = false;
+    }
+}
+function device_define_property(obj, key, value) {
+    if (key in obj) Object.defineProperty(obj, key, {
+        value: value,
+        enumerable: true,
+        configurable: true,
+        writable: true
+    });
+    else obj[key] = value;
+    return obj;
+}
+const defaultScrollUntilTimes = 10;
+const defaultFastScrollDuration = 100;
+const defaultNormalScrollDuration = 1000;
+const IME_STRATEGY_ALWAYS_YADB = 'always-yadb';
+const IME_STRATEGY_YADB_FOR_NON_ASCII = 'yadb-for-non-ascii';
+const debugDevice = (0, logger_.getDebug)('android:device');
+function escapeForShell(text) {
+    return text.replace(/'/g, "'\\''").replace(/\n/g, '\\n');
+}
+const deviceUiautomatorPorts = new Map();
+async function getFreePort() {
+    return new Promise((resolve, reject)=>{
+        const server = createServer();
+        server.unref();
+        server.on('error', reject);
+        server.listen(0, ()=>{
+            const port = server.address().port;
+            server.close(()=>resolve(port));
+        });
+    });
+}
+function uiautomatorHttpRequest(port, path, body, timeoutMs = 3000) {
+    return new Promise((resolve, reject)=>{
+        const bodyBuf = body ? Buffer.from(body, 'utf8') : void 0;
+        const req = request({
+            hostname: '127.0.0.1',
+            port,
+            path,
+            method: body ? 'POST' : 'GET',
+            headers: {
+                ...bodyBuf ? {
+                    'Content-Type': 'application/json',
+                    'Content-Length': bodyBuf.length
+                } : {},
+                Connection: 'close'
+            },
+            timeout: timeoutMs
+        }, (res)=>{
+            let data = '';
+            res.on('data', (chunk)=>{
+                data += chunk.toString();
+            });
+            res.on('end', ()=>resolve(data));
+        });
+        req.on('timeout', ()=>{
+            req.destroy(new Error(`UIAutomator HTTP request timed out after ${timeoutMs}ms`));
+        });
+        req.on('error', reject);
+        if (bodyBuf) req.write(bodyBuf);
+        req.end();
+    });
+}
+class AndroidDevice {
+    actionSpace() {
+        const defaultActions = [
+            defineActionTap(async (param)=>{
+                const element = param.locate;
+                node_assert(element, 'Element not found, cannot tap');
+                await this.mouseClick(element.center[0], element.center[1]);
+            }),
+            defineActionDoubleClick(async (param)=>{
+                const element = param.locate;
+                node_assert(element, 'Element not found, cannot double click');
+                await this.mouseDoubleClick(element.center[0], element.center[1]);
+            }),
+            defineAction({
+                name: 'Input',
+                description: 'Input text into the input field',
+                interfaceAlias: 'aiInput',
+                paramSchema: z.object({
+                    value: z.string().describe('The text to input. Provide the final content for replace/append modes, or an empty string when using clear mode to remove existing text.'),
+                    autoDismissKeyboard: z.boolean().optional().describe('If true, the keyboard will be dismissed after the input is completed. Do not set it unless the user asks you to do so.'),
+                    mode: z.preprocess((val)=>'append' === val ? 'typeOnly' : val, z["enum"]([
+                        'replace',
+                        'clear',
+                        'typeOnly'
+                    ]).default('replace').optional().describe('Input mode: "replace" (default) - clear the field and input the value; "typeOnly" - type the value directly without clearing the field first; "clear" - clear the field without inputting new text.')),
+                    locate: getMidsceneLocationSchema().describe('The input field to be filled').optional()
+                }),
+                sample: {
+                    value: 'test@example.com',
+                    locate: {
+                        prompt: 'the email input field'
+                    }
+                },
+                call: async (param)=>{
+                    const element = param.locate;
+                    if ('typeOnly' !== param.mode) await this.clearInput(element);
+                    if ('clear' === param.mode) return;
+                    if (!param || !param.value) return;
+                    const autoDismissKeyboard = param.autoDismissKeyboard ?? this.options?.autoDismissKeyboard;
+                    await this.keyboardType(param.value, {
+                        autoDismissKeyboard
+                    });
+                }
+            }),
+            defineActionScroll(async (param)=>{
+                const element = param.locate;
+                const startingPoint = element ? {
+                    left: element.center[0],
+                    top: element.center[1]
+                } : void 0;
+                const scrollToEventName = param?.scrollType;
+                if ('scrollToTop' === scrollToEventName) await this.scrollUntilTop(startingPoint);
+                else if ('scrollToBottom' === scrollToEventName) await this.scrollUntilBottom(startingPoint);
+                else if ('scrollToRight' === scrollToEventName) await this.scrollUntilRight(startingPoint);
+                else if ('scrollToLeft' === scrollToEventName) await this.scrollUntilLeft(startingPoint);
+                else if ('singleAction' !== scrollToEventName && scrollToEventName) throw new Error(`Unknown scroll event type: ${scrollToEventName}, param: ${JSON.stringify(param)}`);
+                else {
+                    if (param?.direction !== 'down' && param && param.direction) if ('up' === param.direction) await this.scrollUp(param.distance || void 0, startingPoint);
+                    else if ('left' === param.direction) await this.scrollLeft(param.distance || void 0, startingPoint);
+                    else if ('right' === param.direction) await this.scrollRight(param.distance || void 0, startingPoint);
+                    else throw new Error(`Unknown scroll direction: ${param.direction}`);
+                    else await this.scrollDown(param?.distance || void 0, startingPoint);
+                    await sleep(500);
+                }
+            }),
+            defineActionDragAndDrop(async (param)=>{
+                const from = param.from;
+                const to = param.to;
+                node_assert(from, 'missing "from" param for drag and drop');
+                node_assert(to, 'missing "to" param for drag and drop');
+                await this.mouseDrag({
+                    x: from.center[0],
+                    y: from.center[1]
+                }, {
+                    x: to.center[0],
+                    y: to.center[1]
+                });
+            }),
+            defineActionSwipe(async (param)=>{
+                const { startPoint, endPoint, duration, repeatCount } = normalizeMobileSwipeParam(param, await this.size());
+                for(let i = 0; i < repeatCount; i++)await this.mouseDrag(startPoint, endPoint, duration);
+            }),
+            defineActionKeyboardPress(async (param)=>{
+                await this.keyboardPress(param.keyName);
+            }),
+            defineActionCursorMove(async (param)=>{
+                const arrowKey = 'left' === param.direction ? 'ArrowLeft' : 'ArrowRight';
+                const times = param.times ?? 1;
+                for(let i = 0; i < times; i++){
+                    await this.keyboardPress(arrowKey);
+                    await sleep(100);
+                }
+            }),
+            defineAction({
+                name: 'LongPress',
+                description: 'Trigger a long press on the screen at specified element',
+                paramSchema: z.object({
+                    duration: z.number().optional().describe('The duration of the long press in milliseconds'),
+                    locate: getMidsceneLocationSchema().describe('The element to be long pressed')
+                }),
+                sample: {
+                    locate: {
+                        prompt: 'the message bubble'
+                    }
+                },
+                call: async (param)=>{
+                    const element = param.locate;
+                    if (!element) throw new Error('LongPress requires an element to be located');
+                    const [x, y] = element.center;
+                    await this.longPress(x, y, param?.duration);
+                }
+            }),
+            defineAction({
+                name: 'PullGesture',
+                description: 'Trigger pull down to refresh or pull up actions',
+                paramSchema: z.object({
+                    direction: z["enum"]([
+                        'up',
+                        'down'
+                    ]).describe('The direction to pull'),
+                    distance: z.number().optional().describe('The distance to pull (in pixels)'),
+                    duration: z.number().optional().describe('The duration of the pull (in milliseconds)'),
+                    locate: getMidsceneLocationSchema().optional().describe('The element to start the pull from (optional)')
+                }),
+                sample: {
+                    direction: 'down',
+                    locate: {
+                        prompt: 'the center of the content list area'
+                    }
+                },
+                call: async (param)=>{
+                    const element = param.locate;
+                    const startPoint = element ? {
+                        left: element.center[0],
+                        top: element.center[1]
+                    } : void 0;
+                    if (!param || !param.direction) throw new Error('PullGesture requires a direction parameter');
+                    if ('down' === param.direction) await this.pullDown(startPoint, param.distance, param.duration);
+                    else if ('up' === param.direction) await this.pullUp(startPoint, param.distance, param.duration);
+                    else throw new Error(`Unknown pull direction: ${param.direction}`);
+                }
+            }),
+            defineActionPinch(async (param)=>{
+                const { centerX, centerY, startDistance, endDistance, duration } = normalizePinchParam(param, await this.size());
+                const { x: adjCenterX, y: adjCenterY } = await this.adjustCoordinates(centerX, centerY);
+                const ratio = 0 !== adjCenterX && 0 !== centerX ? adjCenterX / centerX : 1;
+                const adjStartDist = Math.round(startDistance * ratio);
+                const adjEndDist = Math.round(endDistance * ratio);
+                await this.ensureYadb();
+                const adb = await this.getAdb();
+                await adb.shell(`app_process${this.getDisplayArg()} -Djava.class.path=/data/local/tmp/yadb /data/local/tmp com.ysbing.yadb.Main -pinch ${adjCenterX} ${adjCenterY} ${adjStartDist} ${adjEndDist} ${duration}`);
+            }),
+            defineActionClearInput(async (param)=>{
+                await this.clearInput(param.locate);
+            })
+        ];
+        const platformSpecificActions = Object.values(createPlatformActions(this));
+        const customActions = this.customActions || [];
+        return [
+            ...defaultActions,
+            ...platformSpecificActions,
+            ...customActions
+        ];
+    }
+    describe() {
+        return this.description || `DeviceId: ${this.deviceId}`;
+    }
+    async connect() {
+        const adb = await this.getAdb();
+        const adapter = this.getScrcpyAdapter();
+        if (adapter.isEnabled()) try {
+            const deviceInfo = await this.getDevicePhysicalInfo();
+            await adapter.initialize(deviceInfo);
+            console.log(`[midscene] Using scrcpy for screenshots (device: ${this.deviceId})`);
+        } catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            console.warn(`[midscene] Scrcpy unavailable, using ADB fallback (device: ${this.deviceId}): ${msg}`);
+        }
+        return adb;
+    }
+    async getAdb() {
+        if (this.destroyed) throw new Error(`AndroidDevice ${this.deviceId} has been destroyed and cannot execute ADB commands`);
+        if (this.adb) return this.createAdbProxy(this.adb);
+        if (this.connectingAdb) return this.connectingAdb.then((adb)=>this.createAdbProxy(adb));
+        this.connectingAdb = (async ()=>{
+            let error = null;
+            debugDevice(`Initializing ADB with device ID: ${this.deviceId}`);
+            try {
+                const androidAdbPath = this.options?.androidAdbPath || globalConfigManager.getEnvConfigValue(MIDSCENE_ADB_PATH);
+                const remoteAdbHost = this.options?.remoteAdbHost || globalConfigManager.getEnvConfigValue(MIDSCENE_ADB_REMOTE_HOST);
+                const remoteAdbPort = this.options?.remoteAdbPort || globalConfigManager.getEnvConfigValue(MIDSCENE_ADB_REMOTE_PORT);
+                this.adb = new ADB({
+                    udid: this.deviceId,
+                    adbExecTimeout: 60000,
+                    executable: androidAdbPath ? {
+                        path: androidAdbPath,
+                        defaultArgs: []
+                    } : void 0,
+                    remoteAdbHost: remoteAdbHost || void 0,
+                    remoteAdbPort: remoteAdbPort ? Number(remoteAdbPort) : void 0
+                });
+                if (!deviceUiautomatorPorts.has(this.deviceId)) try {
+                    const localPort = await getFreePort();
+                    this.startUIAutomatorProcess();
+                    console.log(`[UIAutomator] Started uiautomator2 server process for ${this.deviceId}`);
+                    await this.adb.forwardPort(localPort, 9008);
+                    deviceUiautomatorPorts.set(this.deviceId, localPort);
+                    console.log(`[UIAutomator] Device ${this.deviceId} routed to local port ${localPort}. Readiness will be checked on first click.`);
+                } catch (e) {
+                    console.warn(`[UIAutomator] Port forward failed for ${this.deviceId}:`, e);
+                }
+                const size = await this.getScreenSize();
+                this.description = `
+DeviceId: ${this.deviceId}
+ScreenSize:
+${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[key]}${'override' === key && size[key] ? ' ✅' : ''}`).join('\n')}
+`;
+                debugDevice('ADB initialized successfully', this.description);
+                return this.adb;
+            } catch (e) {
+                debugDevice(`Failed to initialize ADB: ${e}`);
+                error = new Error(`Unable to connect to device ${this.deviceId}: ${e}`);
+            } finally{
+                this.connectingAdb = null;
+            }
+            if (error) throw error;
+            throw new Error('ADB initialization failed unexpectedly');
+        })();
+        return this.connectingAdb;
+    }
+    createAdbProxy(adb) {
+        return new Proxy(adb, {
+            get: (target, prop)=>{
+                const originalMethod = target[prop];
+                if ('function' != typeof originalMethod) return originalMethod;
+                return async (...args)=>{
+                    try {
+                        debugDevice(`adb ${String(prop)} ${args.join(' ')}`);
+                        const result = await originalMethod.apply(target, args);
+                        debugDevice(`adb ${String(prop)} ${args.join(' ')} end`);
+                        return result;
+                    } catch (error) {
+                        const methodName = String(prop);
+                        const deviceId = this.deviceId;
+                        debugDevice(`ADB error with device ${deviceId} when calling ${methodName}: ${error}`);
+                        throw new Error(`ADB error with device ${deviceId} when calling ${methodName}, please check https://midscenejs.com/integrate-with-android.html#faq : ${error.message}`, {
+                            cause: error
+                        });
+                    }
+                };
+            }
+        });
+    }
+    getScrcpyAdapter() {
+        if (!this.scrcpyAdapter) this.scrcpyAdapter = new ScrcpyDeviceAdapter(this.deviceId, this.options?.scrcpyConfig);
+        return this.scrcpyAdapter;
+    }
+    async getDevicePhysicalInfo() {
+        await this.initializeDevicePixelRatio();
+        const screenSize = await this.getScreenSize();
+        const sizeStr = screenSize.override || screenSize.physical;
+        const match = sizeStr.match(/(\d{1,5})x(\d{1,5})/);
+        if (!match) throw new Error(`Unable to parse screen size: ${sizeStr}`);
+        return {
+            physicalWidth: Number.parseInt(match[1], 10),
+            physicalHeight: Number.parseInt(match[2], 10),
+            dpr: this.devicePixelRatio,
+            orientation: screenSize.orientation,
+            isCurrentOrientation: screenSize.isCurrentOrientation
+        };
+    }
+    setAppNameMapping(mapping) {
+        this.appNameMapping = mapping;
+    }
+    resolvePackageName(appName) {
+        const normalizedAppName = normalizeForComparison(appName);
+        return this.appNameMapping[normalizedAppName];
+    }
+    async launch(uri) {
+        const adb = await this.getAdb();
+        this.uri = uri;
+        try {
+            debugDevice(`Launching app: ${uri}`);
+            if (uri.startsWith('http://') || uri.startsWith('https://') || uri.includes('://')) await adb.startUri(uri);
+            else if (uri.includes('/')) {
+                const [appPackage, appActivity] = uri.split('/');
+                await adb.startApp({
+                    pkg: appPackage,
+                    activity: appActivity
+                });
+            } else {
+                const resolvedUri = this.resolvePackageName(uri) ?? uri;
+                await adb.activateApp(resolvedUri);
+            }
+            debugDevice(`Successfully launched: ${uri}`);
+        } catch (error) {
+            debugDevice(`Error launching ${uri}: ${error}`);
+            throw new Error(`Failed to launch ${uri}: ${error.message}`, {
+                cause: error
+            });
+        }
+        return this;
+    }
+    async execYadb(keyboardContent) {
+        await this.ensureYadb();
+        const adb = await this.getAdb();
+        await adb.shell(`app_process${this.getDisplayArg()} -Djava.class.path=/data/local/tmp/yadb /data/local/tmp com.ysbing.yadb.Main -keyboard '${keyboardContent}'`);
+    }
+    async getElementsInfo() {
+        return [];
+    }
+    async getElementsNodeTree() {
+        return {
+            node: null,
+            children: []
+        };
+    }
+    async getScreenSize() {
+        const shouldCache = !(this.options?.alwaysRefreshScreenInfo ?? false);
+        debugDevice(`getScreenSize: alwaysRefreshScreenInfo=${this.options?.alwaysRefreshScreenInfo}, shouldCache=${shouldCache}, hasCachedSize=${!!this.cachedScreenSize}`);
+        if (shouldCache && this.cachedScreenSize) return this.cachedScreenSize;
+        const adb = await this.getAdb();
+        if ('number' == typeof this.options?.displayId) try {
+            const stdout = await adb.shell('dumpsys display');
+            if (this.options?.usePhysicalDisplayIdForDisplayLookup) {
+                const physicalDisplayId = await this.getPhysicalDisplayId();
+                if (physicalDisplayId) {
+                    const lineRegex = new RegExp(`^.*uniqueId \"local:${physicalDisplayId}\".*$
+`, 'm');
+                    const lineMatch = stdout.match(lineRegex);
+                    if (lineMatch) {
+                        const targetLine = lineMatch[0];
+                        const realMatch = targetLine.match(/real (\d+) x (\d+)/);
+                        const rotationMatch = targetLine.match(/rotation (\d+)/);
+                        if (realMatch && rotationMatch) {
+                            const width = Number(realMatch[1]);
+                            const height = Number(realMatch[2]);
+                            const rotation = Number(rotationMatch[1]);
+                            const sizeStr = `${width}x${height}`;
+                            debugDevice(`Using display info for long ID ${physicalDisplayId}: ${sizeStr}, rotation: ${rotation}`);
+                            const result = {
+                                override: sizeStr,
+                                physical: sizeStr,
+                                orientation: rotation,
+                                isCurrentOrientation: true
+                            };
+                            if (shouldCache) this.cachedScreenSize = result;
+                            return result;
+                        }
+                    }
+                }
+            } else {
+                const viewportRegex = new RegExp(`DisplayViewport{[^}]*displayId=${this.options.displayId}[^}]*}`, 'g');
+                const match = stdout.match(viewportRegex);
+                if (match) {
+                    const targetLine = match[0];
+                    const physicalFrameMatch = targetLine.match(/physicalFrame=Rect\(\d+, \d+ - (\d+), (\d+)\)/);
+                    const orientationMatch = targetLine.match(/orientation=(\d+)/);
+                    if (physicalFrameMatch && orientationMatch) {
+                        const width = Number(physicalFrameMatch[1]);
+                        const height = Number(physicalFrameMatch[2]);
+                        const rotation = Number(orientationMatch[1]);
+                        const sizeStr = `${width}x${height}`;
+                        debugDevice(`Using display info for display ID ${this.options.displayId}: ${sizeStr}, rotation: ${rotation}`);
+                        const result = {
+                            override: sizeStr,
+                            physical: sizeStr,
+                            orientation: rotation,
+                            isCurrentOrientation: true
+                        };
+                        if (shouldCache) this.cachedScreenSize = result;
+                        return result;
+                    }
+                }
+            }
+            debugDevice(`Could not find display info for displayId ${this.options.displayId}`);
+        } catch (e) {
+            debugDevice(`Failed to get size from display info for display ${this.options.displayId}: ${e}`);
+        }
+        const stdout = await adb.shell([
+            'wm',
+            'size'
+        ]);
+        const size = {
+            override: '',
+            physical: ''
+        };
+        const overrideSize = new RegExp(/Override size: ([^\r?\n]+)*/g).exec(stdout);
+        if (overrideSize && overrideSize.length >= 2 && overrideSize[1]) {
+            debugDevice(`Using Override size: ${overrideSize[1].trim()}`);
+            size.override = overrideSize[1].trim();
+        }
+        const physicalSize = new RegExp(/Physical size: ([^\r?\n]+)*/g).exec(stdout);
+        if (physicalSize && physicalSize.length >= 2) {
+            debugDevice(`Using Physical size: ${physicalSize[1].trim()}`);
+            size.physical = physicalSize[1].trim();
+        }
+        const orientation = await this.getDisplayOrientation();
+        if (size.override || size.physical) {
+            const result = {
+                ...size,
+                orientation,
+                isCurrentOrientation: false
+            };
+            if (shouldCache) this.cachedScreenSize = result;
+            return result;
+        }
+        throw new Error(`Failed to get screen size, output: ${stdout}`);
+    }
+    async initializeDevicePixelRatio() {
+        if (this.devicePixelRatioInitialized) return;
+        const densityNum = await this.getDisplayDensity();
+        this.devicePixelRatio = Number(densityNum) / 160;
+        debugDevice(`Initialized device pixel ratio: ${this.devicePixelRatio}`);
+        this.devicePixelRatioInitialized = true;
+    }
+    async getDisplayDensity() {
+        const adb = await this.getAdb();
+        if ('number' == typeof this.options?.displayId) try {
+            const stdout = await adb.shell('dumpsys display');
+            if (this.options?.usePhysicalDisplayIdForDisplayLookup) {
+                const physicalDisplayId = await this.getPhysicalDisplayId();
+                if (physicalDisplayId) {
+                    const lineRegex = new RegExp(`^.*uniqueId \"local:${physicalDisplayId}\".*$
+`, 'm');
+                    const lineMatch = stdout.match(lineRegex);
+                    if (lineMatch) {
+                        const targetLine = lineMatch[0];
+                        const densityMatch = targetLine.match(/density (\d+)/);
+                        if (densityMatch) {
+                            const density = Number(densityMatch[1]);
+                            debugDevice(`Using display density for physical ID ${physicalDisplayId}: ${density}`);
+                            return density;
+                        }
+                    }
+                }
+            } else {
+                const displayDeviceRegex = new RegExp(`DisplayDevice:[\\s\\S]*?mDisplayId=${this.options.displayId}[\\s\\S]*?DisplayInfo{[^}]*density (\\d+)`, 'm');
+                const deviceBlockMatch = stdout.match(displayDeviceRegex);
+                if (deviceBlockMatch) {
+                    const density = Number(deviceBlockMatch[1]);
+                    debugDevice(`Using display density for display ID ${this.options.displayId}: ${density}`);
+                    return density;
+                }
+            }
+        } catch (e) {
+            debugDevice(`Failed to get density from display info: ${e}`);
+        }
+        const density = await adb.getScreenDensity();
+        return density ?? 160;
+    }
+    async getDisplayOrientation() {
+        const shouldCache = !(this.options?.alwaysRefreshScreenInfo ?? false);
+        debugDevice(`getDisplayOrientation: alwaysRefreshScreenInfo=${this.options?.alwaysRefreshScreenInfo}, shouldCache=${shouldCache}, hasCachedOrientation=${null !== this.cachedOrientation}`);
+        if (shouldCache && null !== this.cachedOrientation) return this.cachedOrientation;
+        const adb = await this.getAdb();
+        let orientation = 0;
+        try {
+            const orientationStdout = await adb.shell(`dumpsys${this.getDisplayArg()} input | grep SurfaceOrientation`);
+            const orientationMatch = orientationStdout.match(/SurfaceOrientation:\s*(\d)/);
+            if (!orientationMatch) throw new Error('Failed to get orientation from input');
+            orientation = Number(orientationMatch[1]);
+            debugDevice(`Screen orientation: ${orientation}`);
+        } catch (e) {
+            debugDevice('Failed to get orientation from input, try display');
+            try {
+                const orientationStdout = await adb.shell(`dumpsys${this.getDisplayArg()} display | grep mCurrentOrientation`);
+                const orientationMatch = orientationStdout.match(/mCurrentOrientation=(\d)/);
+                if (!orientationMatch) throw new Error('Failed to get orientation from display');
+                orientation = Number(orientationMatch[1]);
+                debugDevice(`Screen orientation (fallback): ${orientation}`);
+            } catch (e2) {
+                orientation = 0;
+                debugDevice('Failed to get orientation from display, default to 0');
+            }
+        }
+        if (shouldCache) this.cachedOrientation = orientation;
+        return orientation;
+    }
+    async getOrientedPhysicalSize() {
+        const info = await this.getDevicePhysicalInfo();
+        const isLandscape = 1 === info.orientation || 3 === info.orientation;
+        const shouldSwap = true !== info.isCurrentOrientation && isLandscape;
+        return {
+            width: shouldSwap ? info.physicalHeight : info.physicalWidth,
+            height: shouldSwap ? info.physicalWidth : info.physicalHeight
+        };
+    }
+    async size() {
+        const physical = await this.getOrientedPhysicalSize();
+        const scale = 1 / this.devicePixelRatio;
+        return {
+            width: Math.round(physical.width * scale),
+            height: Math.round(physical.height * scale)
+        };
+    }
+    async getAdjustScale() {
+        const shouldCache = !(this.options?.alwaysRefreshScreenInfo ?? false);
+        debugDevice(`getAdjustScale: alwaysRefreshScreenInfo=${this.options?.alwaysRefreshScreenInfo}, shouldCache=${shouldCache}, hasCachedScale=${!!this.cachedAdjustScale}`);
+        if (shouldCache && this.cachedAdjustScale) return this.cachedAdjustScale;
+        const physical = await this.getOrientedPhysicalSize();
+        const { width: logicalW, height: logicalH } = await this.size();
+        const scale = {
+            x: logicalW / physical.width,
+            y: logicalH / physical.height
+        };
+        if (shouldCache) this.cachedAdjustScale = scale;
+        return scale;
+    }
+    async adjustCoordinates(x, y) {
+        const scale = await this.getAdjustScale();
+        return {
+            x: Math.round(x / scale.x),
+            y: Math.round(y / scale.y)
+        };
+    }
+    calculateScrollEndPoint(start, deltaX, deltaY, maxWidth, maxHeight) {
+        const minScrollDistance = 50;
+        let actualScrollDistanceX = 0;
+        let actualScrollDistanceY = 0;
+        if (0 !== deltaX) {
+            const maxAvailableX = deltaX > 0 ? maxWidth - start.x : start.x;
+            actualScrollDistanceX = Math.min(Math.abs(deltaX), maxAvailableX);
+            const minScrollX = Math.min(minScrollDistance, actualScrollDistanceX);
+            actualScrollDistanceX = Math.max(minScrollX, actualScrollDistanceX);
+        }
+        if (0 !== deltaY) {
+            const maxAvailableY = deltaY > 0 ? maxHeight - start.y : start.y;
+            actualScrollDistanceY = Math.min(Math.abs(deltaY), maxAvailableY);
+            const minScrollY = Math.min(minScrollDistance, actualScrollDistanceY);
+            actualScrollDistanceY = Math.max(minScrollY, actualScrollDistanceY);
+        }
+        const endX = Math.round(0 === deltaX ? start.x : deltaX > 0 ? Math.min(maxWidth, start.x + actualScrollDistanceX) : Math.max(0, start.x - actualScrollDistanceX));
+        const endY = Math.round(0 === deltaY ? start.y : deltaY > 0 ? Math.min(maxHeight, start.y + actualScrollDistanceY) : Math.max(0, start.y - actualScrollDistanceY));
+        return {
+            x: endX,
+            y: endY
+        };
+    }
+    async screenshotBase64() {
+        debugDevice('screenshotBase64 begin');
+        const adapter = this.getScrcpyAdapter();
+        if (adapter.isEnabled()) try {
+            debugDevice('Attempting scrcpy screenshot...');
+            const deviceInfo = await this.getDevicePhysicalInfo();
+            const result = await adapter.screenshotBase64(deviceInfo);
+            debugDevice('screenshotBase64 end (scrcpy mode)');
+            return result;
+        } catch (error) {
+            debugDevice(`Scrcpy screenshot failed, falling back to standard ADB method.\nError: ${error}`);
+        }
+        const adb = await this.getAdb();
+        let screenshotBuffer;
+        let localScreenshotPath = null;
+        const screenshotId = Date.now().toString(36);
+        const androidScreenshotPath = `/data/local/tmp/ms_${screenshotId}.png`;
+        const useShellScreencap = 'number' == typeof this.options?.displayId;
+        try {
+            if (!useShellScreencap && this.takeScreenshotFailCount < AndroidDevice.TAKE_SCREENSHOT_FAIL_THRESHOLD) {
+                debugDevice('Taking screenshot via adb.takeScreenshot');
+                screenshotBuffer = await adb.takeScreenshot(null);
+                debugDevice('adb.takeScreenshot completed');
+                if (!screenshotBuffer) {
+                    this.takeScreenshotFailCount++;
+                    throw new Error('Failed to capture screenshot: screenshotBuffer is null');
+                }
+                if (!isValidImageBuffer(screenshotBuffer)) {
+                    debugDevice('Invalid image buffer detected: not a valid image format');
+                    this.takeScreenshotFailCount++;
+                    throw new Error('Screenshot buffer has invalid format: could not find valid image signature');
+                }
+                this.takeScreenshotFailCount = 0;
+            } else {
+                if (this.takeScreenshotFailCount >= AndroidDevice.TAKE_SCREENSHOT_FAIL_THRESHOLD) debugDevice('Skipping takeScreenshot (failed %d consecutive times), using shell screencap directly', this.takeScreenshotFailCount);
+                throw new Error('Using shell screencap directly');
+            }
+            const validScreenshotBufferSize = this.options?.minScreenshotBufferSize ?? 10240;
+            if (validScreenshotBufferSize > 0 && screenshotBuffer.length < validScreenshotBufferSize) {
+                debugDevice(`Screenshot buffer too small: ${screenshotBuffer.length} bytes (minimum: ${validScreenshotBufferSize})`);
+                throw new Error(`Screenshot buffer too small: ${screenshotBuffer.length} bytes (minimum: ${validScreenshotBufferSize})`);
+            }
+        } catch (error) {
+            debugDevice(`Taking screenshot via adb.takeScreenshot failed or was skipped: ${error}`);
+            const screenshotPath = getTmpFile('png');
+            localScreenshotPath = screenshotPath;
+            try {
+                debugDevice('Fallback: taking screenshot via shell screencap');
+                const displayId = this.options?.usePhysicalDisplayIdForScreenshot ? await this.getPhysicalDisplayId() : this.options?.displayId;
+                const displayArg = displayId ? `-d ${displayId}` : '';
+                try {
+                    await adb.shell(`screencap -p ${displayArg} ${androidScreenshotPath}`.trim());
+                    debugDevice('adb.shell screencap completed');
+                } catch (screencapError) {
+                    debugDevice('screencap failed, using forceScreenshot');
+                    await this.forceScreenshot(androidScreenshotPath);
+                    debugDevice('forceScreenshot completed');
+                }
+                debugDevice('Pulling screenshot file from device');
+                await adb.pull(androidScreenshotPath, screenshotPath);
+                debugDevice(`adb.pull completed, local path: ${screenshotPath}`);
+                screenshotBuffer = await external_node_fs_["default"].promises.readFile(screenshotPath);
+                const validScreenshotBufferSize = this.options?.minScreenshotBufferSize ?? 10240;
+                if (!screenshotBuffer || validScreenshotBufferSize > 0 && screenshotBuffer.length < validScreenshotBufferSize) throw new Error(`Fallback screenshot validation failed: buffer size ${screenshotBuffer?.length || 0} bytes (minimum: ${validScreenshotBufferSize})`);
+                if (!isValidImageBuffer(screenshotBuffer)) throw new Error('Fallback screenshot buffer has invalid PNG format');
+                debugDevice(`Fallback screenshot validated successfully: ${screenshotBuffer.length} bytes`);
+            } finally{
+                const adbPath = adb.executable?.path ?? 'adb';
+                const child = execFile(adbPath, [
+                    '-s',
+                    this.deviceId,
+                    'shell',
+                    `rm ${androidScreenshotPath}`
+                ], {
+                    timeout: 3000
+                }, (err)=>{
+                    if (err) debugDevice('Failed to delete remote screenshot: %s', err.message);
+                });
+                child.unref();
+            }
+        }
+        if (!screenshotBuffer) throw new Error('Failed to capture screenshot: all methods failed');
+        debugDevice('Converting to base64');
+        const result = createImgBase64ByFormat('png', screenshotBuffer.toString('base64'));
+        if (localScreenshotPath) {
+            debugDevice(`Deleting local screenshot: ${localScreenshotPath}`);
+            (0, external_node_fs_.unlink)(localScreenshotPath, (unlinkError)=>{
+                if (unlinkError) debugDevice(`Failed to delete screenshot: ${unlinkError}`);
+            });
+        }
+        debugDevice('screenshotBase64 end');
+        return result;
+    }
+    async clearInput(element) {
+        if (element) await this.mouseClick(element.center[0], element.center[1]);
+        await this.ensureYadb();
+        const adb = await this.getAdb();
+        const IME_STRATEGY = (this.options?.imeStrategy || globalConfigManager.getEnvConfigValue(MIDSCENE_ANDROID_IME_STRATEGY)) ?? IME_STRATEGY_YADB_FOR_NON_ASCII;
+        if (IME_STRATEGY === IME_STRATEGY_YADB_FOR_NON_ASCII) await adb.clearTextField(100);
+        else await adb.shell(`app_process${this.getDisplayArg()} -Djava.class.path=/data/local/tmp/yadb /data/local/tmp com.ysbing.yadb.Main -keyboard "~CLEAR~"`);
+        if (await adb.isSoftKeyboardPresent()) return;
+        if (element) await this.mouseClick(element.center[0], element.center[1]);
+    }
+    async forceScreenshot(path) {
+        await this.ensureYadb();
+        const adb = await this.getAdb();
+        await adb.shell(`app_process -Djava.class.path=/data/local/tmp/yadb /data/local/tmp com.ysbing.yadb.Main -screenshot ${path}`);
+    }
+    async url() {
+        return '';
+    }
+    async scrollUntilTop(startPoint) {
+        if (startPoint) {
+            const { height } = await this.size();
+            const start = {
+                x: Math.round(startPoint.left),
+                y: Math.round(startPoint.top)
+            };
+            const end = {
+                x: start.x,
+                y: Math.round(height)
+            };
+            await repeat(defaultScrollUntilTimes, ()=>this.mouseDrag(start, end, defaultFastScrollDuration));
+            await sleep(1000);
+            return;
+        }
+        await repeat(defaultScrollUntilTimes, ()=>this.scroll(0, -9999999, defaultFastScrollDuration));
+        await sleep(1000);
+    }
+    async scrollUntilBottom(startPoint) {
+        if (startPoint) {
+            const start = {
+                x: Math.round(startPoint.left),
+                y: Math.round(startPoint.top)
+            };
+            const end = {
+                x: start.x,
+                y: 0
+            };
+            await repeat(defaultScrollUntilTimes, ()=>this.mouseDrag(start, end, defaultFastScrollDuration));
+            await sleep(1000);
+            return;
+        }
+        await repeat(defaultScrollUntilTimes, ()=>this.scroll(0, 9999999, defaultFastScrollDuration));
+        await sleep(1000);
+    }
+    async scrollUntilLeft(startPoint) {
+        if (startPoint) {
+            const { width } = await this.size();
+            const start = {
+                x: Math.round(startPoint.left),
+                y: Math.round(startPoint.top)
+            };
+            const end = {
+                x: Math.round(width),
+                y: start.y
+            };
+            await repeat(defaultScrollUntilTimes, ()=>this.mouseDrag(start, end, defaultFastScrollDuration));
+            await sleep(1000);
+            return;
+        }
+        await repeat(defaultScrollUntilTimes, ()=>this.scroll(-9999999, 0, defaultFastScrollDuration));
+        await sleep(1000);
+    }
+    async scrollUntilRight(startPoint) {
+        if (startPoint) {
+            const start = {
+                x: Math.round(startPoint.left),
+                y: Math.round(startPoint.top)
+            };
+            const end = {
+                x: 0,
+                y: start.y
+            };
+            await repeat(defaultScrollUntilTimes, ()=>this.mouseDrag(start, end, defaultFastScrollDuration));
+            await sleep(1000);
+            return;
+        }
+        await repeat(defaultScrollUntilTimes, ()=>this.scroll(9999999, 0, defaultFastScrollDuration));
+        await sleep(1000);
+    }
+    async scrollUp(distance, startPoint) {
+        const { height } = await this.size();
+        const scrollDistance = Math.round(distance || height);
+        if (startPoint) {
+            const start = {
+                x: Math.round(startPoint.left),
+                y: Math.round(startPoint.top)
+            };
+            const end = this.calculateScrollEndPoint(start, 0, scrollDistance, 0, height);
+            await this.mouseDrag(start, end);
+            return;
+        }
+        await this.scroll(0, -scrollDistance);
+    }
+    async scrollDown(distance, startPoint) {
+        const { height } = await this.size();
+        const scrollDistance = Math.round(distance || height);
+        if (startPoint) {
+            const start = {
+                x: Math.round(startPoint.left),
+                y: Math.round(startPoint.top)
+            };
+            const end = this.calculateScrollEndPoint(start, 0, -scrollDistance, 0, height);
+            await this.mouseDrag(start, end);
+            return;
+        }
+        await this.scroll(0, scrollDistance);
+    }
+    async scrollLeft(distance, startPoint) {
+        const { width } = await this.size();
+        const scrollDistance = Math.round(distance || width);
+        if (startPoint) {
+            const start = {
+                x: Math.round(startPoint.left),
+                y: Math.round(startPoint.top)
+            };
+            const end = this.calculateScrollEndPoint(start, scrollDistance, 0, width, 0);
+            await this.mouseDrag(start, end);
+            return;
+        }
+        await this.scroll(-scrollDistance, 0);
+    }
+    async scrollRight(distance, startPoint) {
+        const { width } = await this.size();
+        const scrollDistance = Math.round(distance || width);
+        if (startPoint) {
+            const start = {
+                x: Math.round(startPoint.left),
+                y: Math.round(startPoint.top)
+            };
+            const end = this.calculateScrollEndPoint(start, -scrollDistance, 0, width, 0);
+            await this.mouseDrag(start, end);
+            return;
+        }
+        await this.scroll(scrollDistance, 0);
+    }
+    async ensureYadb() {
+        if (!this.yadbPushed) {
+            const adb = await this.getAdb();
+            const androidPkgJson = (0, external_node_module_.createRequire)(import.meta.url).resolve('@midscene/android/package.json');
+            const yadbBin = external_node_path_["default"].join(external_node_path_["default"].dirname(androidPkgJson), 'bin', 'yadb');
+            await adb.push(yadbBin, '/data/local/tmp');
+            this.yadbPushed = true;
+        }
+    }
+    shouldUseYadbForText(text) {
+        const hasNonAscii = /[\x80-\uFFFF]/.test(text);
+        const hasFormatSpecifiers = /%[a-zA-Z]/.test(text);
+        const hasShellSpecialChars = /[\\`$]/.test(text);
+        const hasBothQuotes = text.includes('"') && text.includes("'");
+        return hasNonAscii || hasFormatSpecifiers || hasShellSpecialChars || hasBothQuotes;
+    }
+    async keyboardType(text, options) {
+        if (!text) return;
+        const adb = await this.getAdb();
+        const IME_STRATEGY = (this.options?.imeStrategy || globalConfigManager.getEnvConfigValue(MIDSCENE_ANDROID_IME_STRATEGY)) ?? IME_STRATEGY_YADB_FOR_NON_ASCII;
+        const shouldAutoDismissKeyboard = options?.autoDismissKeyboard ?? this.options?.autoDismissKeyboard ?? true;
+        const useYadb = IME_STRATEGY === IME_STRATEGY_ALWAYS_YADB || IME_STRATEGY === IME_STRATEGY_YADB_FOR_NON_ASCII && this.shouldUseYadbForText(text);
+        if (useYadb) await this.execYadb(escapeForShell(text));
+        else {
+            const segments = text.split('\n');
+            for(let i = 0; i < segments.length; i++){
+                if (segments[i].length > 0) await adb.inputText(segments[i]);
+                if (i < segments.length - 1) await adb.keyevent(66);
+            }
+        }
+        if (true === shouldAutoDismissKeyboard) await this.hideKeyboard(options);
+    }
+    normalizeKeyName(key) {
+        const keyMap = {
+            enter: 'Enter',
+            backspace: 'Backspace',
+            tab: 'Tab',
+            escape: 'Escape',
+            esc: 'Escape',
+            home: 'Home',
+            end: 'End',
+            arrowup: 'ArrowUp',
+            arrowdown: 'ArrowDown',
+            arrowleft: 'ArrowLeft',
+            arrowright: 'ArrowRight',
+            up: 'ArrowUp',
+            down: 'ArrowDown',
+            left: 'ArrowLeft',
+            right: 'ArrowRight'
+        };
+        const lowerKey = key.toLowerCase();
+        return keyMap[lowerKey] || key;
+    }
+    async keyboardPress(key) {
+        const keyCodeMap = {
+            Enter: 66,
+            Backspace: 67,
+            Tab: 61,
+            ArrowUp: 19,
+            ArrowDown: 20,
+            ArrowLeft: 21,
+            ArrowRight: 22,
+            Escape: 111,
+            Home: 3,
+            End: 123
+        };
+        const adb = await this.getAdb();
+        const normalizedKey = this.normalizeKeyName(key);
+        const keyCode = keyCodeMap[normalizedKey];
+        if (void 0 !== keyCode) await adb.keyevent(keyCode);
+        else if (1 === key.length) {
+            const asciiCode = key.toUpperCase().charCodeAt(0);
+            if (asciiCode >= 65 && asciiCode <= 90) await adb.keyevent(asciiCode - 36);
+        }
+    }
+    startUIAutomatorProcess() {
+        if (this.uiautomatorProcess || this.destroyed) return;
+        const adbPath = this.adb?.executable?.path ?? 'adb';
+        this.uiautomatorProcess = execFile(adbPath, [
+            '-s',
+            this.deviceId,
+            'shell',
+            'CLASSPATH=/data/local/tmp/u2.jar app_process / com.wetest.uia2.Main'
+        ], {
+            timeout: 0
+        }, ()=>{
+            this.uiautomatorProcess = null;
+            this.uiautomatorKnownHealthy = false;
+            debugDevice(`[UIAutomator] server process exited for ${this.deviceId}`);
+        });
+        this.uiautomatorProcess.unref();
+    }
+    async ensureUIAutomatorReady(port, timeoutMs = 5000) {
+        if (this.uiautomatorConfirmedUnavailable) return false;
+        if (this.uiautomatorKnownHealthy && this.uiautomatorProcess) return true;
+        const processWasAlive = !!this.uiautomatorProcess;
+        if (!this.uiautomatorProcess) {
+            console.log(`[UIAutomator] server not running on ${this.deviceId}, starting...`);
+            this.startUIAutomatorProcess();
+        }
+        try {
+            const adb = await this.getAdb();
+            await adb.forwardPort(port, 9008);
+        } catch (e) {}
+        const deadline = Date.now() + timeoutMs;
+        let firstIteration = true;
+        while(Date.now() < deadline){
+            if (!firstIteration || !processWasAlive) await new Promise((r)=>setTimeout(r, 500));
+            firstIteration = false;
+            try {
+                const text = await uiautomatorHttpRequest(port, '/ping', void 0, 1000);
+                if ('pong' === text.trim()) {
+                    console.log(`[UIAutomator] ✅ server ready on ${this.deviceId} (port ${port})`);
+                    this.uiautomatorKnownHealthy = true;
+                    return true;
+                }
+            } catch (_) {}
+        }
+        if (this.uiautomatorProcess) {
+            this.uiautomatorProcess.kill();
+            this.uiautomatorProcess = null;
+        }
+        console.warn(`[UIAutomator] ⚠️  server did not respond within ${timeoutMs}ms on ${this.deviceId}. Marking as unavailable. Run 'python -m uiautomator2 init' to install it.`);
+        this.uiautomatorConfirmedUnavailable = true;
+        return false;
+    }
+    async mouseClick(x, y) {
+        const adb = await this.getAdb();
+        const { x: adjustedX, y: adjustedY } = await this.adjustCoordinates(x, y);
+        const localPort = deviceUiautomatorPorts.get(this.deviceId);
+        if (localPort && !this.uiautomatorConfirmedUnavailable) {
+            const performUIAutomatorClick = async ()=>{
+                try {
+                    console.log(`[UIAutomator] click(${adjustedX}, ${adjustedY}) via port ${localPort}`);
+                    const body = JSON.stringify({
+                        jsonrpc: "2.0",
+                        id: 1,
+                        method: "click",
+                        params: [
+                            adjustedX,
+                            adjustedY
+                        ]
+                    });
+                    const resultText = await uiautomatorHttpRequest(localPort, '/jsonrpc/0', body);
+                    const result = JSON.parse(resultText);
+                    return true === result.result;
+                } catch (err) {
+                    return false;
+                }
+            };
+            if (this.uiautomatorKnownHealthy) {
+                const success = await performUIAutomatorClick();
+                if (success) return void debugDevice("[UIAutomator] click success");
+                this.uiautomatorKnownHealthy = false;
+                console.warn(`[UIAutomator] optimistic click failed on ${this.deviceId}, attempting to recover...`);
+            }
+            const ready = await this.ensureUIAutomatorReady(localPort);
+            if (ready) {
+                const success = await performUIAutomatorClick();
+                if (success) {
+                    this.uiautomatorKnownHealthy = true;
+                    debugDevice("[UIAutomator] click success after recovery");
+                    return;
+                }
+                this.uiautomatorKnownHealthy = false;
+                console.warn("[UIAutomator] click unexpected response or failed after recovery, falling back to adb swipe");
+            }
+        }
+        console.log(`[ADB swipe] input swipe ${adjustedX} ${adjustedY} ${adjustedX} ${adjustedY} 150`);
+        await adb.shell(`input${this.getDisplayArg()} swipe ${adjustedX} ${adjustedY} ${adjustedX} ${adjustedY} 150`);
+    }
+    async mouseDoubleClick(x, y) {
+        const adb = await this.getAdb();
+        const { x: adjustedX, y: adjustedY } = await this.adjustCoordinates(x, y);
+        const tapCommand = `input${this.getDisplayArg()} tap ${adjustedX} ${adjustedY}`;
+        await adb.shell(tapCommand);
+        await sleep(50);
+        await adb.shell(tapCommand);
+    }
+    async mouseMove() {
+        return Promise.resolve();
+    }
+    async mouseDrag(from, to, duration) {
+        const adb = await this.getAdb();
+        const { x: fromX, y: fromY } = await this.adjustCoordinates(from.x, from.y);
+        const { x: toX, y: toY } = await this.adjustCoordinates(to.x, to.y);
+        const swipeDuration = duration ?? defaultNormalScrollDuration;
+        await adb.shell(`input${this.getDisplayArg()} swipe ${fromX} ${fromY} ${toX} ${toY} ${swipeDuration}`);
+    }
+    async scroll(deltaX, deltaY, duration) {
+        if (0 === deltaX && 0 === deltaY) throw new Error('Scroll distance cannot be zero in both directions');
+        const { width, height } = await this.size();
+        const n = 4;
+        const startX = Math.round(deltaX < 0 ? width / n * (n - 1) : width / n);
+        const startY = Math.round(deltaY < 0 ? height / n * (n - 1) : height / n);
+        const maxPositiveDeltaX = startX;
+        const maxNegativeDeltaX = width - startX;
+        const maxPositiveDeltaY = startY;
+        const maxNegativeDeltaY = height - startY;
+        deltaX = Math.max(-maxNegativeDeltaX, Math.min(deltaX, maxPositiveDeltaX));
+        deltaY = Math.max(-maxNegativeDeltaY, Math.min(deltaY, maxPositiveDeltaY));
+        const endX = Math.round(startX - deltaX);
+        const endY = Math.round(startY - deltaY);
+        const { x: adjustedStartX, y: adjustedStartY } = await this.adjustCoordinates(startX, startY);
+        const { x: adjustedEndX, y: adjustedEndY } = await this.adjustCoordinates(endX, endY);
+        const adb = await this.getAdb();
+        const swipeDuration = duration ?? defaultNormalScrollDuration;
+        await adb.shell(`input${this.getDisplayArg()} swipe ${adjustedStartX} ${adjustedStartY} ${adjustedEndX} ${adjustedEndY} ${swipeDuration}`);
+    }
+    async destroy() {
+        if (this.destroyed) return;
+        this.destroyed = true;
+        this.cachedPhysicalDisplayId = void 0;
+        this.cachedScreenSize = null;
+        this.cachedOrientation = null;
+        this.cachedAdjustScale = null;
+        const localPort = deviceUiautomatorPorts.get(this.deviceId);
+        if (localPort && this.adb) {
+            try {
+                await this.adb.removePortForward(localPort);
+                debugDevice(`[UIAutomator] Removed port forwarding for ${this.deviceId} on port ${localPort}`);
+            } catch (e) {}
+            deviceUiautomatorPorts.delete(this.deviceId);
+        }
+        if (this.uiautomatorProcess) {
+            this.uiautomatorProcess.kill();
+            this.uiautomatorProcess = null;
+            debugDevice(`[UIAutomator] Killed uiautomator2 server process for ${this.deviceId}`);
+        }
+        if (this.scrcpyAdapter) {
+            await this.scrcpyAdapter.disconnect();
+            this.scrcpyAdapter = null;
+        }
+        try {
+            if (this.adb) this.adb = null;
+        } catch (error) {
+            console.error('Error during cleanup:', error);
+        }
+        this.connectingAdb = null;
+        this.yadbPushed = false;
+    }
+    async getTimestamp() {
+        const adb = await this.getAdb();
+        try {
+            const stdout = await adb.shell('date +%s%3N');
+            const timestamp = Number.parseInt(stdout.trim(), 10);
+            if (Number.isNaN(timestamp)) throw new Error(`Invalid timestamp format: ${stdout}`);
+            debugDevice(`Got device time: ${timestamp}`);
+            return timestamp;
+        } catch (error) {
+            debugDevice(`Failed to get device time: ${error}`);
+            throw new Error(`Failed to get device time: ${error}`);
+        }
+    }
+    async back() {
+        const adb = await this.getAdb();
+        await adb.shell(`input${this.getDisplayArg()} keyevent 4`);
+    }
+    async home() {
+        const adb = await this.getAdb();
+        await adb.shell(`input${this.getDisplayArg()} keyevent 3`);
+    }
+    async recentApps() {
+        const adb = await this.getAdb();
+        await adb.shell(`input${this.getDisplayArg()} keyevent 187`);
+    }
+    async longPress(x, y, duration = 2000) {
+        const adb = await this.getAdb();
+        const { x: adjustedX, y: adjustedY } = await this.adjustCoordinates(x, y);
+        await adb.shell(`input${this.getDisplayArg()} swipe ${adjustedX} ${adjustedY} ${adjustedX} ${adjustedY} ${duration}`);
+    }
+    async pullDown(startPoint, distance, duration = 800) {
+        const { width, height } = await this.size();
+        const start = startPoint ? {
+            x: Math.round(startPoint.left),
+            y: Math.round(startPoint.top)
+        } : {
+            x: Math.round(width / 2),
+            y: Math.round(0.15 * height)
+        };
+        const pullDistance = Math.round(distance || 0.5 * height);
+        const end = {
+            x: start.x,
+            y: start.y + pullDistance
+        };
+        await this.pullDrag(start, end, duration);
+        await sleep(200);
+    }
+    async pullDrag(from, to, duration) {
+        const adb = await this.getAdb();
+        const { x: fromX, y: fromY } = await this.adjustCoordinates(from.x, from.y);
+        const { x: toX, y: toY } = await this.adjustCoordinates(to.x, to.y);
+        await adb.shell(`input${this.getDisplayArg()} swipe ${fromX} ${fromY} ${toX} ${toY} ${duration}`);
+    }
+    async pullUp(startPoint, distance, duration = 600) {
+        const { width, height } = await this.size();
+        const start = startPoint ? {
+            x: Math.round(startPoint.left),
+            y: Math.round(startPoint.top)
+        } : {
+            x: Math.round(width / 2),
+            y: Math.round(0.85 * height)
+        };
+        const pullDistance = Math.round(distance || 0.4 * height);
+        const end = {
+            x: start.x,
+            y: start.y - pullDistance
+        };
+        await this.pullDrag(start, end, duration);
+        await sleep(100);
+    }
+    getDisplayArg() {
+        return 'number' == typeof this.options?.displayId ? ` -d ${this.options.displayId}` : '';
+    }
+    async getPhysicalDisplayId() {
+        if (void 0 !== this.cachedPhysicalDisplayId) return this.cachedPhysicalDisplayId;
+        if ('number' != typeof this.options?.displayId) {
+            this.cachedPhysicalDisplayId = null;
+            return null;
+        }
+        const adb = await this.getAdb();
+        try {
+            const stdout = await adb.shell(`dumpsys SurfaceFlinger --display-id ${this.options.displayId}`);
+            const regex = new RegExp(`Display (\\d+) \\(HWC display ${this.options.displayId}\\):`);
+            const displayMatch = stdout.match(regex);
+            if (displayMatch?.[1]) {
+                this.cachedPhysicalDisplayId = displayMatch[1];
+                debugDevice(`Found and cached physical display ID: ${displayMatch[1]} for display ID: ${this.options.displayId}`);
+                return this.cachedPhysicalDisplayId;
+            }
+            this.cachedPhysicalDisplayId = null;
+            debugDevice(`Could not find physical display ID for display ID: ${this.options.displayId}`);
+            return null;
+        } catch (error) {
+            debugDevice(`Error getting physical display ID: ${error}`);
+            this.cachedPhysicalDisplayId = null;
+            return null;
+        }
+    }
+    async hideKeyboard(options, timeoutMs = 1000) {
+        const adb = await this.getAdb();
+        const keyboardDismissStrategy = options?.keyboardDismissStrategy ?? this.options?.keyboardDismissStrategy ?? 'esc-first';
+        const keyboardStatus = await adb.isSoftKeyboardPresent();
+        const isKeyboardShown = 'boolean' == typeof keyboardStatus ? keyboardStatus : keyboardStatus?.isKeyboardShown;
+        if (!isKeyboardShown) {
+            debugDevice('Keyboard has no UI; no closing necessary');
+            return false;
+        }
+        const keyCodes = 'back-first' === keyboardDismissStrategy ? [
+            4,
+            111
+        ] : [
+            111,
+            4
+        ];
+        for (const keyCode of keyCodes){
+            await adb.keyevent(keyCode);
+            const startTime = Date.now();
+            const intervalMs = 100;
+            while(Date.now() - startTime < timeoutMs){
+                await sleep(intervalMs);
+                const currentStatus = await adb.isSoftKeyboardPresent();
+                const isStillShown = 'boolean' == typeof currentStatus ? currentStatus : currentStatus?.isKeyboardShown;
+                if (!isStillShown) {
+                    debugDevice(`Keyboard hidden successfully with keycode ${keyCode}`);
+                    return true;
+                }
+            }
+            debugDevice(`Keyboard still shown after keycode ${keyCode}, trying next key`);
+        }
+        console.warn('Warning: Failed to hide the software keyboard after trying both ESC and BACK keys');
+        return false;
+    }
+    constructor(deviceId, options){
+        device_define_property(this, "deviceId", void 0);
+        device_define_property(this, "yadbPushed", false);
+        device_define_property(this, "devicePixelRatio", 1);
+        device_define_property(this, "devicePixelRatioInitialized", false);
+        device_define_property(this, "adb", null);
+        device_define_property(this, "connectingAdb", null);
+        device_define_property(this, "destroyed", false);
+        device_define_property(this, "description", void 0);
+        device_define_property(this, "customActions", void 0);
+        device_define_property(this, "cachedScreenSize", null);
+        device_define_property(this, "cachedOrientation", null);
+        device_define_property(this, "cachedPhysicalDisplayId", void 0);
+        device_define_property(this, "scrcpyAdapter", null);
+        device_define_property(this, "appNameMapping", {});
+        device_define_property(this, "cachedAdjustScale", null);
+        device_define_property(this, "takeScreenshotFailCount", 0);
+        device_define_property(this, "uiautomatorProcess", null);
+        device_define_property(this, "uiautomatorConfirmedUnavailable", false);
+        device_define_property(this, "uiautomatorKnownHealthy", false);
+        device_define_property(this, "interfaceType", 'android');
+        device_define_property(this, "uri", void 0);
+        device_define_property(this, "options", void 0);
+        node_assert(deviceId, 'deviceId is required for AndroidDevice');
+        this.deviceId = deviceId;
+        this.options = options;
+        this.customActions = options?.customActions;
+    }
+}
+device_define_property(AndroidDevice, "TAKE_SCREENSHOT_FAIL_THRESHOLD", 3);
+const runAdbShellParamSchema = z.object({
+    command: z.string().describe('ADB shell command to execute')
+});
+const launchParamSchema = z.object({
+    uri: z.string().describe('App name, package name, or URL to launch. Prioritize using the exact package name or URL the user has provided. If none provided, use the accurate app name.')
+});
+const createPlatformActions = (device)=>({
+        RunAdbShell: defineAction({
+            name: 'RunAdbShell',
+            description: 'Execute ADB shell command on Android device',
+            interfaceAlias: 'runAdbShell',
+            paramSchema: runAdbShellParamSchema,
+            sample: {
+                command: 'dumpsys window displays | grep -E "mCurrentFocus"'
+            },
+            call: async (param)=>{
+                if (!param.command || '' === param.command.trim()) throw new Error('RunAdbShell requires a non-empty command parameter');
+                const adb = await device.getAdb();
+                return await adb.shell(param.command);
+            }
+        }),
+        Launch: defineAction({
+            name: 'Launch',
+            description: 'Launch an Android app or URL',
+            interfaceAlias: 'launch',
+            paramSchema: launchParamSchema,
+            sample: {
+                uri: 'com.example.app'
+            },
+            call: async (param)=>{
+                if (!param.uri || '' === param.uri.trim()) throw new Error('Launch requires a non-empty uri parameter');
+                await device.launch(param.uri);
+            }
+        }),
+        AndroidBackButton: defineAction({
+            name: 'AndroidBackButton',
+            description: 'Trigger the system "back" operation on Android devices',
+            call: async ()=>{
+                await device.back();
+            }
+        }),
+        AndroidHomeButton: defineAction({
+            name: 'AndroidHomeButton',
+            description: 'Trigger the system "home" operation on Android devices',
+            call: async ()=>{
+                await device.home();
+            }
+        }),
+        AndroidRecentAppsButton: defineAction({
+            name: 'AndroidRecentAppsButton',
+            description: 'Trigger the system "recent apps" operation on Android devices',
+            call: async ()=>{
+                await device.recentApps();
+            }
+        })
+    });
+const defaultAppNameMapping = {
+    微信: 'com.tencent.mm',
+    QQ: 'com.tencent.mobileqq',
+    微博: 'com.sina.weibo',
+    淘宝: 'com.taobao.taobao',
+    京东: 'com.jingdong.app.mall',
+    拼多多: 'com.xunmeng.pinduoduo',
+    淘宝闪购: 'com.taobao.taobao',
+    京东秒送: 'com.jingdong.app.mall',
+    小红书: 'com.xingin.xhs',
+    豆瓣: 'com.douban.frodo',
+    知乎: 'com.zhihu.android',
+    高德地图: 'com.autonavi.minimap',
+    百度地图: 'com.baidu.BaiduMap',
+    美团: 'com.sankuai.meituan',
+    大众点评: 'com.dianping.v1',
+    饿了么: 'me.ele',
+    肯德基: 'com.yek.android.kfc.activitys',
+    携程: 'ctrip.android.view',
+    铁路12306: 'com.MobileTicket',
+    12306: 'com.MobileTicket',
+    去哪儿旅行: 'com.Qunar',
+    滴滴出行: 'com.sdu.didi.psnger',
+    bilibili: 'tv.danmaku.bili',
+    抖音: 'com.ss.android.ugc.aweme',
+    懂车帝: 'com.ss.android.auto',
+    快手: 'com.smile.gifmaker',
+    腾讯视频: 'com.tencent.qqlive',
+    爱奇艺: 'com.qiyi.video',
+    优酷视频: 'com.youku.phone',
+    芒果TV: 'com.hunantv.imgo.activity',
+    红果短剧: 'com.phoenix.read',
+    网易云音乐: 'com.netease.cloudmusic',
+    QQ音乐: 'com.tencent.qqmusic',
+    汽水音乐: 'com.luna.music',
+    喜马拉雅: 'com.ximalaya.ting.android',
+    番茄小说: 'com.dragon.read',
+    七猫免费小说: 'com.kmxs.reader',
+    飞书: 'com.ss.android.lark',
+    QQ邮箱: 'com.tencent.androidqqmail',
+    豆包: 'com.larus.nova',
+    Keep: 'com.gotokeep.keep',
+    美柚: 'com.lingan.seeyou',
+    腾讯新闻: 'com.tencent.news',
+    今日头条: 'com.ss.android.article.news',
+    贝壳找房: 'com.lianjia.beike',
+    安居客: 'com.anjuke.android.app',
+    同花顺: 'com.hexin.plat.android',
+    星穹铁道: 'com.miHoYo.hkrpg',
+    '崩坏：星穹铁道': 'com.miHoYo.hkrpg',
+    恋与深空: 'com.papegames.lysk.cn',
+    'Android System Settings': 'com.android.settings',
+    Settings: 'com.android.settings',
+    'Audio Recorder': 'com.android.soundrecorder',
+    Clock: 'com.android.deskclock',
+    Contacts: 'com.android.contacts',
+    Files: 'com.android.fileexplorer',
+    'Google Chrome': 'com.android.chrome',
+    Gmail: 'com.google.android.gm',
+    'Google Files': 'com.google.android.apps.nbu.files',
+    'Google Calendar': 'com.google.android.calendar',
+    'Google Chat': 'com.google.android.apps.dynamite',
+    'Google Clock': 'com.google.android.deskclock',
+    'Google Contacts': 'com.google.android.contacts',
+    'Google Docs': 'com.google.android.apps.docs.editors.docs',
+    'Google Drive': 'com.google.android.apps.docs',
+    'Google Fit': 'com.google.android.apps.fitness',
+    'Google Keep': 'com.google.android.keep',
+    'Google Maps': 'com.google.android.apps.maps',
+    'Google Play Books': 'com.google.android.apps.books',
+    'Google Play Store': 'com.android.vending',
+    'Google Slides': 'com.google.android.apps.docs.editors.slides',
+    'Google Tasks': 'com.google.android.apps.tasks',
+    Bluecoins: 'com.rammigsoftware.bluecoins',
+    Broccoli: 'com.flauschcode.broccoli',
+    'Booking.com': 'com.booking',
+    Duolingo: 'com.duolingo',
+    Expedia: 'com.expedia.bookings',
+    Joplin: 'net.cozic.joplin',
+    McDonald: 'com.mcdonalds.app',
+    Osmand: 'net.osmand',
+    PiMusicPlayer: 'com.Project100Pi.themusicplayer',
+    Quora: 'com.quora.android',
+    Reddit: 'com.reddit.frontpage',
+    RetroMusic: 'code.name.monkey.retromusic',
+    SimpleCalendarPro: 'com.scientificcalculatorplus.simplecalculator.basiccalculator.mathcalc',
+    SimpleSMSMessenger: 'com.simplemobiletools.smsmessenger',
+    Telegram: 'org.telegram.messenger',
+    Temu: 'com.einnovation.temu',
+    TikTok: 'com.zhiliaoapp.musically',
+    Twitter: 'com.twitter.android',
+    X: 'com.twitter.android',
+    VLC: 'org.videolan.vlc',
+    WeChat: 'com.tencent.mm',
+    WhatsApp: 'com.whatsapp'
+};
+const debugUtils = (0, logger_.getDebug)('android:utils');
+const DETAIL_LOOKUP_ADB_TIMEOUT_MS = 8000;
+const DETAIL_LOOKUP_STEP_TIMEOUT_MS = 2000;
+function cleanProp(value) {
+    const normalized = value?.trim();
+    return normalized ? normalized : void 0;
+}
+function parseResolution(stdout) {
+    const overrideSize = stdout.match(/Override size:\s*([^\r\n]+)/);
+    if (overrideSize?.[1]) return overrideSize[1].trim();
+    const physicalSize = stdout.match(/Physical size:\s*([^\r\n]+)/);
+    if (physicalSize?.[1]) return physicalSize[1].trim();
+}
+async function withTimeout(promise, timeoutMs, label) {
+    let timer;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_, reject)=>{
+                timer = setTimeout(()=>{
+                    reject(new Error(`${label} timed out after ${timeoutMs}ms`));
+                }, timeoutMs);
+            })
+        ]);
+    } finally{
+        if (timer) clearTimeout(timer);
+    }
+}
+async function createAdbForDetailLookup() {
+    return await ADB.createADB({
+        adbExecTimeout: DETAIL_LOOKUP_ADB_TIMEOUT_MS
+    });
+}
+async function getConnectedDevices() {
+    try {
+        const adb = await ADB.createADB({
+            adbExecTimeout: 60000
+        });
+        const devices = await adb.getConnectedDevices();
+        debugUtils(`Found ${devices.length} connected devices: `, devices);
+        return devices;
+    } catch (error) {
+        console.error('Failed to get device list:', error);
+        throw new Error(`Unable to get connected Android device list, please check https://midscenejs.com/integrate-with-android.html#faq : ${error.message}`, {
+            cause: error
+        });
+    }
+}
+async function getConnectedDevicesWithDetails() {
+    const devices = await getConnectedDevices();
+    if (0 === devices.length) return [];
+    return await Promise.all(devices.map(async (device)=>{
+        const detailedDevice = {
+            ...device
+        };
+        try {
+            const adb = await createAdbForDetailLookup();
+            adb.setDeviceId(device.udid);
+            const [modelResult, brandResult, sizeResult, densityResult] = await Promise.allSettled([
+                withTimeout(adb.shell([
+                    'getprop',
+                    'ro.product.model'
+                ]), DETAIL_LOOKUP_STEP_TIMEOUT_MS, `Android model lookup for ${device.udid}`),
+                withTimeout(adb.shell([
+                    'getprop',
+                    'ro.product.brand'
+                ]), DETAIL_LOOKUP_STEP_TIMEOUT_MS, `Android brand lookup for ${device.udid}`),
+                withTimeout(adb.shell([
+                    'wm',
+                    'size'
+                ]), DETAIL_LOOKUP_STEP_TIMEOUT_MS, `Android resolution lookup for ${device.udid}`),
+                withTimeout(adb.getScreenDensity(), DETAIL_LOOKUP_STEP_TIMEOUT_MS, `Android density lookup for ${device.udid}`)
+            ]);
+            if ('fulfilled' === modelResult.status) detailedDevice.model = cleanProp(modelResult.value);
+            if ('fulfilled' === brandResult.status) detailedDevice.brand = cleanProp(brandResult.value);
+            if ('fulfilled' === sizeResult.status) detailedDevice.resolution = parseResolution(sizeResult.value);
+            if ('fulfilled' === densityResult.status && 'number' == typeof densityResult.value) detailedDevice.density = densityResult.value;
+        } catch (error) {
+            debugUtils(`Failed to enrich Android device ${device.udid}:`, error);
+        }
+        return detailedDevice;
+    }));
+}
+function agent_define_property(obj, key, value) {
+    if (key in obj) Object.defineProperty(obj, key, {
+        value: value,
+        enumerable: true,
+        configurable: true,
+        writable: true
+    });
+    else obj[key] = value;
+    return obj;
+}
+const debugAgent = (0, logger_.getDebug)('android:agent');
+class AndroidAgent extends Agent {
+    async launch(uri) {
+        const action = this.wrapActionInActionSpace('Launch');
+        return action({
+            uri
+        });
+    }
+    async runAdbShell(command) {
+        const action = this.wrapActionInActionSpace('RunAdbShell');
+        return action({
+            command
+        });
+    }
+    createActionWrapper(name) {
+        const action = this.wrapActionInActionSpace(name);
+        return (...args)=>action(args[0]);
+    }
+    constructor(device, opts){
+        super(device, opts), agent_define_property(this, "back", void 0), agent_define_property(this, "home", void 0), agent_define_property(this, "recentApps", void 0), agent_define_property(this, "appNameMapping", void 0);
+        this.appNameMapping = mergeAndNormalizeAppNameMapping(defaultAppNameMapping, opts?.appNameMapping);
+        device.setAppNameMapping(this.appNameMapping);
+        this.back = this.createActionWrapper('AndroidBackButton');
+        this.home = this.createActionWrapper('AndroidHomeButton');
+        this.recentApps = this.createActionWrapper('AndroidRecentAppsButton');
+    }
+}
+async function agentFromAdbDevice(deviceId, opts) {
+    if (!deviceId) {
+        const devices = await getConnectedDevices();
+        if (0 === devices.length) throw new Error('No Android devices found. Please connect an Android device and ensure ADB is properly configured. Run `adb devices` to verify device connection.');
+        deviceId = devices[0].udid;
+        debugAgent('deviceId not specified, will use the first device (id = %s)', deviceId);
+    }
+    const device = new AndroidDevice(deviceId, opts || {});
+    await device.connect();
+    return new AndroidAgent(device, opts);
+}
+const debug = (0, logger_.getDebug)('mcp:android-tools');
+class AndroidMidsceneTools extends BaseMidsceneTools {
+    createTemporaryDevice() {
+        return new AndroidDevice('temp-for-action-space', {});
+    }
+    async ensureAgent(deviceId) {
+        if (this.agent && deviceId) {
+            try {
+                await this.agent.destroy?.();
+            } catch (error) {
+                debug('Failed to destroy agent during cleanup:', error);
+            }
+            this.agent = void 0;
+        }
+        if (this.agent) return this.agent;
+        debug('Creating Android agent with deviceId:', deviceId || 'auto-detect');
+        const agent = await agentFromAdbDevice(deviceId, {
+            autoDismissKeyboard: false
+        });
+        this.agent = agent;
+        return agent;
+    }
+    preparePlatformTools() {
+        return [
+            {
+                name: 'android_connect',
+                description: 'Connect to Android device via ADB. If deviceId not provided, uses the first available device.',
+                schema: {
+                    deviceId: z.string().optional().describe('Android device ID (from adb devices)')
+                },
+                handler: async ({ deviceId })=>{
+                    const agent = await this.ensureAgent(deviceId);
+                    const screenshot = await agent.page.screenshotBase64();
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Connected to Android device${deviceId ? `: ${deviceId}` : ' (auto-detected)'}`
+                            },
+                            ...this.buildScreenshotContent(screenshot)
+                        ],
+                        isError: false
+                    };
+                }
+            },
+            {
+                name: 'android_disconnect',
+                description: 'Disconnect from current Android device and release ADB resources',
+                schema: {},
+                handler: this.createDisconnectHandler('Android device')
+            }
+        ];
+    }
+}
+export { AndroidAgent, AndroidDevice, AndroidMidsceneTools, ScrcpyDeviceAdapter, agentFromAdbDevice, getConnectedDevices, getConnectedDevicesWithDetails, overrideAIConfig };