@astur-mobile/android 0.1.0-beta.0

package/dist/index.js

@@ -0,0 +1,1338 @@
+import { existsSync, readdirSync } from 'node:fs';
+import { get as httpGet } from 'node:http';
+import { createServer as createNetServer } from 'node:net';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { centerOf, connectNativeAgentClient, findElement, formatSelector, AsturError, delay, preparePointerTargetForKeyboard, waitFor } from '@astur-mobile/core';
+import { run, runText, spawnCommand, spawnDetached } from './command.js';
+import { parseUiAutomatorXml } from './uiautomatorXml.js';
+export function createAndroidDriver(options = {}) {
+    return new AndroidDriver(options);
+}
+export class AndroidDriver {
+    platform = 'android';
+    adbPath;
+    emulatorPath;
+    aaptPath;
+    constructor(options = {}) {
+        this.adbPath = options.adbPath ?? process.env.ASTUR_ADB ?? 'adb';
+        this.emulatorPath = options.emulatorPath ?? process.env.ASTUR_EMULATOR ?? resolveEmulatorPath();
+        this.aaptPath = options.aaptPath ?? process.env.ASTUR_AAPT;
+    }
+    async doctor() {
+        const checks = [];
+        try {
+            const version = await runText(this.adbPath, ['version']);
+            checks.push({
+                id: 'android.adb',
+                label: 'ADB',
+                status: 'pass',
+                message: firstLine(version)
+            });
+        }
+        catch (error) {
+            checks.push({
+                id: 'android.adb',
+                label: 'ADB',
+                status: 'fail',
+                message: error instanceof Error ? error.message : String(error),
+                fix: 'Install Android SDK platform-tools and ensure adb is on PATH.'
+            });
+        }
+        const sdkRoot = process.env.ANDROID_HOME ?? process.env.ANDROID_SDK_ROOT;
+        checks.push({
+            id: 'android.sdk',
+            label: 'Android SDK',
+            status: sdkRoot ? 'pass' : 'warn',
+            message: sdkRoot ? sdkRoot : 'ANDROID_HOME or ANDROID_SDK_ROOT is not set.',
+            fix: sdkRoot ? undefined : 'Set ANDROID_HOME or ANDROID_SDK_ROOT to your Android SDK path.'
+        });
+        try {
+            const avds = await this.listAvds();
+            checks.push({
+                id: 'android.avds',
+                label: 'Android AVDs',
+                status: avds.length ? 'pass' : 'warn',
+                message: avds.length ? `${avds.length} AVD(s) available: ${avds.join(', ')}` : 'No Android AVDs detected.',
+                fix: avds.length ? undefined : 'Create an emulator from Android Studio Device Manager.'
+            });
+        }
+        catch (error) {
+            checks.push({
+                id: 'android.avds',
+                label: 'Android AVDs',
+                status: 'warn',
+                message: error instanceof Error ? error.message : String(error),
+                fix: 'Ensure the Android emulator binary is on PATH.'
+            });
+        }
+        try {
+            const devices = await this.listDevices();
+            checks.push({
+                id: 'android.devices',
+                label: 'Android devices',
+                status: devices.some((device) => device.state === 'online') ? 'pass' : 'warn',
+                message: devices.length ? `${devices.length} device(s) detected.` : 'No Android devices detected.',
+                fix: devices.length ? undefined : 'Start an emulator or connect a device with USB debugging enabled.'
+            });
+        }
+        catch (error) {
+            checks.push({
+                id: 'android.devices',
+                label: 'Android devices',
+                status: 'fail',
+                message: error instanceof Error ? error.message : String(error)
+            });
+        }
+        return checks;
+    }
+    async listDevices() {
+        const output = await runText(this.adbPath, ['devices', '-l']);
+        return parseAdbDevices(output);
+    }
+    async listAvds() {
+        const output = await runText(this.emulatorPath, ['-list-avds']);
+        return output.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+    }
+    async createSession(capabilities) {
+        const resolvedCapabilities = await this.resolveCapabilities(capabilities);
+        if (resolvedCapabilities.device.cloud) {
+            throw new AsturError('CLOUD_PROVIDER_NOT_IMPLEMENTED', 'BrowserStack execution is scaffolded by Astur init, but the cloud driver is not implemented in this alpha. Use a local Android emulator or real device for now.', { cloud: resolvedCapabilities.device.cloud });
+        }
+        let devices = await this.listDevices();
+        let device = selectDevice(devices, resolvedCapabilities.device);
+        if (!device && shouldAutoBoot(resolvedCapabilities.device)) {
+            await this.bootConfiguredEmulator(resolvedCapabilities.device);
+            devices = await this.listDevices();
+            device = selectDevice(devices, resolvedCapabilities.device);
+        }
+        if (!device) {
+            const selector = resolvedCapabilities.device;
+            const pinnedEmulator = selector.kind === 'emulator' || Boolean(selector.id?.startsWith('emulator-'));
+            const hint = pinnedEmulator && !selector.avd
+                ? ' To let Astur boot it automatically when it is offline, also set device.avd (and optionally autoBoot: true) — an emulator cannot be started from its id alone.'
+                : '';
+            throw new AsturError('DEVICE_NOT_FOUND', `No matching Android device is online.${hint}`, {
+                selector,
+                devices
+            });
+        }
+        const nativeAgent = await this.resolveNativeAgent(resolvedCapabilities, device);
+        return new AndroidSession(this.adbPath, device, resolvedCapabilities, nativeAgent);
+    }
+    async resolveNativeAgent(capabilities, device) {
+        if (capabilities.agent.mode === 'off') {
+            return undefined;
+        }
+        const endpoint = capabilities.agent.endpoint ?? process.env.ASTUR_ANDROID_AGENT_ENDPOINT;
+        if (!endpoint) {
+            const hasBundledAgentArtifacts = capabilities.agent.install && Boolean(resolveAndroidAgentArtifacts());
+            const runtime = await this.tryBootstrapBundledNativeAgent(capabilities, device);
+            if (runtime) {
+                return runtime;
+            }
+            if (capabilities.agent.mode === 'required' || !allowsLegacyFallback(capabilities, 'failure')) {
+                throw new AsturError('ANDROID_AGENT_ENDPOINT_REQUIRED', 'Android native-agent mode is required, but no endpoint or built Android agent APKs were available. Set use.astur.agent.endpoint, ASTUR_ANDROID_AGENT_ENDPOINT, or build packages/android-agent.');
+            }
+            if (!hasBundledAgentArtifacts) {
+                warnAndroidAgentFallback('Android native agent is not configured and built agent APKs were not found. Using legacy ADB/XML interaction path.');
+            }
+            return undefined;
+        }
+        try {
+            const client = await connectNativeAgentClient({
+                endpoint,
+                platform: 'android',
+                handshakeTimeout: capabilities.agent.launchTimeout,
+                commandTimeout: capabilities.agent.commandTimeout
+            });
+            return { client };
+        }
+        catch (error) {
+            if (capabilities.agent.mode === 'required' || !allowsLegacyFallback(capabilities, 'failure')) {
+                throw new AsturError('ANDROID_AGENT_CONNECT_FAILED', `Failed to connect to Android native agent at ${endpoint}.`, {
+                    endpoint,
+                    cause: error
+                });
+            }
+            warnAndroidAgentFallback(`Failed to connect to Android native agent at ${endpoint}. Using legacy ADB/XML interaction path.`);
+            return undefined;
+        }
+    }
+    async tryBootstrapBundledNativeAgent(capabilities, device) {
+        if (!capabilities.agent.install) {
+            return undefined;
+        }
+        const artifacts = resolveAndroidAgentArtifacts();
+        if (!artifacts) {
+            return undefined;
+        }
+        const config = resolveAndroidAgentRuntimeConfig();
+        const hostPort = config.hostPort ?? await findFreePort();
+        const endpoint = `http://127.0.0.1:${hostPort}`;
+        const adb = (args) => run(this.adbPath, ['-s', device.id, ...args]);
+        let agentProcess;
+        try {
+            if (await shouldInstallAndroidAgent(adb, config)) {
+                await adb(['install', '-r', artifacts.appApkPath]);
+                await adb(['install', '-r', artifacts.testApkPath]);
+            }
+            await adb(['forward', `tcp:${hostPort}`, `tcp:${config.devicePort}`]);
+            agentProcess = spawnCommand(this.adbPath, [
+                '-s',
+                device.id,
+                'shell',
+                'am',
+                'instrument',
+                '-w',
+                '-e',
+                'asturPort',
+                String(config.devicePort),
+                `${config.testPackage}/${config.runnerClass}`
+            ]);
+            const client = await waitForAndroidAgent(endpoint, capabilities);
+            return {
+                client,
+                hostPort,
+                packageName: config.packageName,
+                process: agentProcess
+            };
+        }
+        catch (error) {
+            agentProcess?.kill('SIGINT');
+            await adb(['forward', '--remove', `tcp:${hostPort}`]).catch(() => undefined);
+            if (capabilities.agent.mode === 'required' || !allowsLegacyFallback(capabilities, 'failure')) {
+                throw new AsturError('ANDROID_AGENT_START_FAILED', 'Failed to install or start the Android native agent.', {
+                    device,
+                    artifacts,
+                    endpoint,
+                    cause: error
+                });
+            }
+            warnAndroidAgentFallback('Failed to bootstrap the built Android native agent. Using legacy ADB/XML interaction path.');
+            return undefined;
+        }
+    }
+    async resolveCapabilities(capabilities) {
+        return {
+            ...capabilities,
+            app: await this.resolveApp(capabilities.app)
+        };
+    }
+    async resolveApp(app) {
+        if (!app?.path || (app.packageName && app.activity)) {
+            return app;
+        }
+        const metadata = await this.readApkMetadata(app.path);
+        return {
+            ...app,
+            packageName: app.packageName ?? metadata.packageName,
+            activity: app.activity ?? metadata.launchActivity
+        };
+    }
+    async readApkMetadata(path) {
+        const aaptPath = this.aaptPath ?? resolveAaptPath();
+        if (!aaptPath) {
+            throw new AsturError('AAPT_NOT_FOUND', 'Cannot infer Android package metadata because aapt was not found. Set ASTUR_AAPT or provide app.packageName in config.');
+        }
+        const output = await runText(aaptPath, ['dump', 'badging', path]);
+        return parseAaptBadging(output);
+    }
+    async bootConfiguredEmulator(selector) {
+        if (!selector.avd) {
+            return;
+        }
+        const args = [
+            '-avd',
+            selector.avd,
+            '-no-snapshot-save',
+            '-no-audio',
+            '-no-boot-anim'
+        ];
+        if (selector.headless !== false) {
+            args.push('-no-window');
+        }
+        if (selector.wipeData) {
+            args.push('-wipe-data');
+        }
+        args.push(...(selector.emulatorArgs ?? []));
+        const child = spawnDetached(this.emulatorPath, args);
+        let launchError;
+        child.once('error', (error) => {
+            launchError = new AsturError('EMULATOR_LAUNCH_FAILED', `Could not launch the Android emulator "${this.emulatorPath}": ${error.message}. Install the Android SDK emulator and make sure it is on PATH, or set ASTUR_EMULATOR / ANDROID_HOME.`, { avd: selector.avd, emulatorPath: this.emulatorPath });
+        });
+        child.once('exit', (code, signal) => {
+            if (code != null && code !== 0) {
+                launchError = new AsturError('EMULATOR_LAUNCH_FAILED', `The Android emulator for AVD "${selector.avd}" exited (code ${code}) before finishing boot. The AVD name may be wrong, or an instance of it may already be running.`, { avd: selector.avd, code, signal });
+            }
+        });
+        await this.waitForBoot(selector, () => launchError);
+    }
+    async waitForBoot(selector, getLaunchError) {
+        const timeout = selector.bootTimeout ?? 120_000;
+        const startedAt = Date.now();
+        let lastDevices = [];
+        while (Date.now() - startedAt <= timeout) {
+            const launchError = getLaunchError?.();
+            if (launchError) {
+                throw launchError;
+            }
+            lastDevices = await this.listDevices().catch(() => []);
+            const device = selectDevice(lastDevices, { ...selector, kind: 'emulator' });
+            if (device) {
+                const bootCompleted = await runText(this.adbPath, ['-s', device.id, 'shell', 'getprop', 'sys.boot_completed'])
+                    .then((value) => value.trim() === '1')
+                    .catch(() => false);
+                if (bootCompleted) {
+                    return;
+                }
+            }
+            await delay(1_000);
+        }
+        throw new AsturError('EMULATOR_BOOT_TIMEOUT', `Timed out waiting for Android AVD ${selector.avd} to boot.`, {
+            selector,
+            devices: lastDevices
+        });
+    }
+}
+class AndroidSession {
+    deviceInfo;
+    capabilities;
+    adbPath;
+    nativeAgent;
+    nativeAgentRuntime;
+    unsupportedAgentMethods = new Set();
+    recording;
+    forwardedWebViewPorts = new Set();
+    constructor(adbPath, deviceInfo, capabilities, nativeAgentRuntime) {
+        this.adbPath = adbPath;
+        this.deviceInfo = deviceInfo;
+        this.capabilities = capabilities;
+        this.nativeAgentRuntime = nativeAgentRuntime;
+        this.nativeAgent = nativeAgentRuntime?.client;
+    }
+    async close() {
+        if (this.recording) {
+            await this.stopRecording().catch(() => undefined);
+        }
+        await Promise.all([...this.forwardedWebViewPorts].map((port) => this.adb(['forward', '--remove', `tcp:${port}`]).catch(() => undefined)));
+        this.forwardedWebViewPorts.clear();
+        if (this.nativeAgentRuntime?.hostPort) {
+            await this.adb(['forward', '--remove', `tcp:${this.nativeAgentRuntime.hostPort}`]).catch(() => undefined);
+        }
+        this.nativeAgentRuntime?.process?.kill('SIGINT');
+        if (this.nativeAgentRuntime?.packageName) {
+            await this.adb(['shell', 'am', 'force-stop', this.nativeAgentRuntime.packageName]).catch(() => undefined);
+        }
+        return;
+    }
+    async installApp(path) {
+        await this.adb(['install', '-r', path]);
+    }
+    async isAppInstalled(identifier) {
+        const output = await this.adbText(['shell', 'pm', 'path', identifier]).catch(() => '');
+        return output
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .some((line) => line.startsWith('package:'));
+    }
+    async uninstallApp(identifier) {
+        await this.adb(['uninstall', identifier]);
+    }
+    async launchApp(options = {}) {
+        if (options.url) {
+            await this.openWeb(options.url);
+            return;
+        }
+        const app = options.app ?? this.capabilities.app;
+        const packageName = app?.packageName ?? app?.bundleId;
+        if (!packageName) {
+            throw new AsturError('ANDROID_PACKAGE_REQUIRED', 'Android launch requires app.packageName. Astur does not infer package names from APKs yet.');
+        }
+        if (app?.activity) {
+            await this.adb(['shell', 'am', 'start', '-n', `${packageName}/${app.activity}`]);
+            return;
+        }
+        await this.adb([
+            'shell',
+            'monkey',
+            '-p',
+            packageName,
+            '-c',
+            'android.intent.category.LAUNCHER',
+            '1'
+        ]);
+    }
+    async terminateApp() {
+        const packageName = this.resolvePackageName();
+        await this.adb(['shell', 'am', 'force-stop', packageName]);
+    }
+    async clearAppData(identifier) {
+        await this.adb(['shell', 'pm', 'clear', identifier]);
+    }
+    async clearAppCache(identifier) {
+        await this.adb(['shell', 'pm', 'clear', '--cache-only', identifier]);
+    }
+    async grantPermission(identifier, permission) {
+        await this.adb(['shell', 'pm', 'grant', identifier, normalizeAndroidPermission(permission)]);
+    }
+    async revokePermission(identifier, permission) {
+        await this.adb(['shell', 'pm', 'revoke', identifier, normalizeAndroidPermission(permission)]);
+    }
+    async resetApp(options = {}) {
+        const app = options.app ?? {
+            ...this.capabilities.app,
+            path: options.path ?? this.capabilities.app?.path,
+            packageName: options.packageName ?? this.capabilities.app?.packageName,
+            bundleId: options.bundleId ?? this.capabilities.app?.bundleId
+        };
+        const packageName = options.packageName ?? options.bundleId ?? app.packageName ?? app.bundleId;
+        if (!packageName) {
+            throw new AsturError('ANDROID_PACKAGE_REQUIRED', 'Android reset requires app.packageName.');
+        }
+        await this.adb(['shell', 'am', 'force-stop', packageName]).catch(() => undefined);
+        if (options.reinstall) {
+            const path = options.path ?? app.path;
+            if (!path) {
+                throw new AsturError('APP_PATH_REQUIRED', 'Android reinstall reset requires an app path.');
+            }
+            await this.adb(['uninstall', packageName]).catch(() => undefined);
+            await this.installApp(path);
+        }
+        else {
+            await this.clearAppData(packageName);
+        }
+        if (options.launch) {
+            await this.launchApp({ app });
+        }
+    }
+    async setOrientation(orientation) {
+        if (this.nativeAgent?.info.capabilities.includes('device.setOrientation')) {
+            try {
+                const command = await this.tryNativeCommand('device.setOrientation', { orientation });
+                if (command.ok) {
+                    return;
+                }
+            }
+            catch {
+                // Orientation is a lifecycle control; fall through to Android shell APIs
+                // when the agent cannot apply it directly.
+            }
+        }
+        const rotation = androidRotationForOrientation(orientation);
+        await this.adb(['shell', 'settings', 'put', 'system', 'accelerometer_rotation', '0']).catch(() => undefined);
+        await this.adb(['shell', 'settings', 'put', 'system', 'user_rotation', String(rotation)]).catch(() => undefined);
+        try {
+            await this.adb(['shell', 'cmd', 'window', 'user-rotation', 'lock', String(rotation)]);
+            await this.adb(['shell', 'cmd', 'window', 'fixed-to-user-rotation', 'enabled']).catch(() => undefined);
+        }
+        catch {
+            // Older Android images may not expose cmd window user-rotation.
+            // The settings writes above are the compatibility path.
+        }
+        await delay(500);
+    }
+    async lockDevice() {
+        await this.pressKey('SLEEP');
+    }
+    async unlockDevice() {
+        await this.pressKey('WAKEUP');
+        await this.adb(['shell', 'wm', 'dismiss-keyguard']).catch(() => undefined);
+    }
+    async isDeviceLocked() {
+        return parseAndroidLockState(await this.adbText(['shell', 'dumpsys', 'window']));
+    }
+    async getTree() {
+        const command = await this.tryNativeCommand('tree.get');
+        if (command.ok) {
+            return command.result;
+        }
+        const remotePath = '/sdcard/astur-window.xml';
+        await this.adb(['shell', 'uiautomator', 'dump', remotePath]);
+        const xml = await this.adbText(['shell', 'cat', remotePath]);
+        return parseUiAutomatorXml(xml);
+    }
+    async findElement(selector) {
+        const command = await this.tryNativeCommand('element.find', { selector });
+        if (command.ok) {
+            return command.result;
+        }
+        return findElement(await this.getTree(), selector);
+    }
+    async waitForElement(selector, options = {}) {
+        const state = options.state ?? 'attached';
+        const command = await this.tryNativeCommand('element.wait', {
+            selector,
+            options: {
+                ...options,
+                state
+            }
+        });
+        if (command.ok && command.result) {
+            return command.result;
+        }
+        return waitFor(async () => {
+            const element = await this.findElement(selector);
+            if (!element) {
+                return undefined;
+            }
+            if (state === 'visible' && !element.visible) {
+                return undefined;
+            }
+            if (state === 'hidden') {
+                return element.visible ? undefined : element;
+            }
+            return element;
+        }, {
+            timeout: options.timeout ?? this.capabilities.timeout,
+            interval: options.interval,
+            message: `Timed out waiting for ${formatSelector(selector)} to be ${state}`
+        });
+    }
+    async waitForElementHidden(selector, options = {}) {
+        const command = await this.tryNativeCommand('element.wait', {
+            selector,
+            options: {
+                ...options,
+                state: 'hidden'
+            }
+        });
+        if (command.ok) {
+            return;
+        }
+        await waitFor(async () => {
+            const element = await this.findElement(selector);
+            return !element || !element.visible;
+        }, {
+            timeout: options.timeout ?? this.capabilities.timeout,
+            interval: options.interval,
+            message: `Timed out waiting for ${formatSelector(selector)} to be hidden`
+        });
+    }
+    async tapElement(selector, options = {}) {
+        const command = await this.tryNativeCommand('element.tap', { selector, options });
+        if (command.ok) {
+            return;
+        }
+        let element = await this.waitForElement(selector, { ...options, state: 'visible' });
+        const dismissed = await preparePointerTargetForKeyboard(this, centerOf(element.bounds), options.keyboard);
+        if (dismissed) {
+            element = await this.waitForElement(selector, { ...options, state: 'visible' });
+        }
+        await this.tap(centerOf(element.bounds));
+    }
+    async doubleTapElement(selector, options = {}) {
+        const command = await this.tryNativeCommand('element.doubleTap', { selector, options });
+        if (command.ok) {
+            return;
+        }
+        let element = await this.waitForElement(selector, { ...options, state: 'visible' });
+        const dismissed = await preparePointerTargetForKeyboard(this, centerOf(element.bounds), options.keyboard);
+        if (dismissed) {
+            element = await this.waitForElement(selector, { ...options, state: 'visible' });
+        }
+        await this.doubleTap(centerOf(element.bounds), { intervalMs: options.intervalMs });
+    }
+    async longPressElement(selector, options = {}) {
+        const command = await this.tryNativeCommand('element.longPress', { selector, options });
+        if (command.ok) {
+            return;
+        }
+        let element = await this.waitForElement(selector, { ...options, state: 'visible' });
+        const dismissed = await preparePointerTargetForKeyboard(this, centerOf(element.bounds), options.keyboard);
+        if (dismissed) {
+            element = await this.waitForElement(selector, { ...options, state: 'visible' });
+        }
+        await this.longPress(centerOf(element.bounds), { durationMs: options.durationMs });
+    }
+    async fillElement(selector, value, options = {}) {
+        const command = await this.tryNativeCommand('element.fill', { selector, value, options });
+        if (command.ok) {
+            return;
+        }
+        const element = await this.waitForElement(selector, { ...options, state: 'visible' });
+        await preparePointerTargetForKeyboard(this, centerOf(element.bounds), options.keyboard);
+        await this.tap(centerOf(element.bounds));
+        await this.adb(['shell', 'input', 'text', escapeAndroidInputText(value)]);
+    }
+    async dragElement(selector, target, options = {}) {
+        const command = await this.tryNativeCommand('element.drag', { selector, target, options });
+        if (command.ok) {
+            return;
+        }
+        let source = await this.waitForElement(selector, { ...options, state: 'visible' });
+        const dismissed = await preparePointerTargetForKeyboard(this, centerOf(source.bounds), options.keyboard);
+        if (dismissed) {
+            source = await this.waitForElement(selector, { ...options, state: 'visible' });
+        }
+        const end = isElementSelectorTarget(target)
+            ? centerOf((await this.waitForElement(target.selector, {
+                timeout: options.timeout,
+                interval: options.interval,
+                state: 'visible'
+            })).bounds)
+            : target;
+        await this.drag({
+            start: centerOf(source.bounds),
+            end,
+            durationMs: options.durationMs
+        });
+    }
+    async tap(target) {
+        const command = await this.tryNativeCommand('gesture.tap', { target });
+        if (command.ok) {
+            return;
+        }
+        await this.adb(['shell', 'input', 'tap', String(target.x), String(target.y)]);
+    }
+    async doubleTap(target, options = {}) {
+        const command = await this.tryNativeCommand('gesture.doubleTap', { target, options });
+        if (command.ok) {
+            return;
+        }
+        await this.tap(target);
+        await delay(options.intervalMs ?? 80);
+        await this.tap(target);
+    }
+    async longPress(target, options = {}) {
+        const command = await this.tryNativeCommand('gesture.longPress', { target, options });
+        if (command.ok) {
+            return;
+        }
+        const durationMs = options.durationMs ?? 800;
+        await this.adb([
+            'shell',
+            'input',
+            'swipe',
+            String(target.x),
+            String(target.y),
+            String(target.x),
+            String(target.y),
+            String(durationMs)
+        ]);
+    }
+    async fill(selector, value) {
+        await this.fillElement(selector, value);
+    }
+    async pressKey(key) {
+        await this.adb(['shell', 'input', 'keyevent', normalizeAndroidKey(key)]);
+    }
+    async swipe(gesture) {
+        const command = await this.tryNativeCommand('gesture.swipe', { gesture });
+        if (command.ok) {
+            return;
+        }
+        await this.adb([
+            'shell',
+            'input',
+            'swipe',
+            String(gesture.start.x),
+            String(gesture.start.y),
+            String(gesture.end.x),
+            String(gesture.end.y),
+            String(gesture.durationMs ?? 300)
+        ]);
+    }
+    async drag(gesture) {
+        const command = await this.tryNativeCommand('gesture.drag', { gesture });
+        if (command.ok) {
+            return;
+        }
+        await this.adb([
+            'shell',
+            'input',
+            'swipe',
+            String(gesture.start.x),
+            String(gesture.start.y),
+            String(gesture.end.x),
+            String(gesture.end.y),
+            String(gesture.durationMs ?? 700)
+        ]);
+    }
+    async startRecording() {
+        if (this.recording) {
+            throw new AsturError('RECORDING_ALREADY_STARTED', 'Android screen recording is already running for this session.');
+        }
+        const remotePath = `/sdcard/astur-recording-${process.pid}-${Date.now()}.mp4`;
+        const child = spawnCommand(this.adbPath, ['-s', this.deviceInfo.id, 'shell', 'screenrecord', remotePath]);
+        this.recording = { child, remotePath };
+        await delay(500);
+    }
+    async stopRecording(options = {}) {
+        const recording = this.recording;
+        if (!recording) {
+            return undefined;
+        }
+        this.recording = undefined;
+        await this.adb(['shell', 'pkill', '-2', 'screenrecord']).catch(() => undefined);
+        await waitForProcessExit(recording.child, 10_000);
+        await this.waitForRemoteFileStable(recording.remotePath, 5_000);
+        if (options.discard) {
+            await this.adb(['shell', 'rm', '-f', recording.remotePath]).catch(() => undefined);
+            return undefined;
+        }
+        try {
+            const result = await this.adb(['exec-out', 'cat', recording.remotePath], 200 * 1024 * 1024);
+            return result.stdout.length ? result.stdout : undefined;
+        }
+        finally {
+            await this.adb(['shell', 'rm', '-f', recording.remotePath]).catch(() => undefined);
+        }
+    }
+    async waitForRemoteFileStable(remotePath, timeoutMs) {
+        const deadline = Date.now() + timeoutMs;
+        let lastSize = -1;
+        let stableReads = 0;
+        while (Date.now() <= deadline) {
+            const size = await this.remoteFileSize(remotePath).catch(() => 0);
+            if (size > 0 && size === lastSize) {
+                stableReads += 1;
+                if (stableReads >= 2) {
+                    return;
+                }
+            }
+            else {
+                stableReads = 0;
+                lastSize = size;
+            }
+            await delay(250);
+        }
+    }
+    async remoteFileSize(remotePath) {
+        const output = await this.adbText(['shell', 'stat', '-c', '%s', remotePath]);
+        const size = Number(output.trim());
+        return Number.isFinite(size) ? size : 0;
+    }
+    async screenshot() {
+        const result = await this.adb(['exec-out', 'screencap', '-p']);
+        return result.stdout;
+    }
+    async pushFile(localPath, remotePath) {
+        await this.adb(['push', localPath, remotePath]);
+    }
+    async pullFile(remotePath) {
+        const result = await this.adb(['exec-out', 'cat', remotePath], 200 * 1024 * 1024);
+        return result.stdout;
+    }
+    async removeFile(remotePath) {
+        await this.adb(['shell', 'rm', '-rf', remotePath]);
+    }
+    async listFiles(remotePath) {
+        const output = await this.adbText(['shell', 'ls', '-la', remotePath]);
+        return parseAndroidLs(output, remotePath);
+    }
+    async openWeb(url) {
+        await this.adb(['shell', 'am', 'start', '-a', 'android.intent.action.VIEW', '-d', url]);
+    }
+    async listContexts() {
+        const sockets = parseAndroidWebViewSockets(await this.adbText(['shell', 'cat', '/proc/net/unix']));
+        return [
+            {
+                id: 'native',
+                type: 'native',
+                title: 'Native'
+            },
+            ...sockets.map((socket) => ({
+                id: socket,
+                type: 'webview',
+                socket
+            }))
+        ];
+    }
+    async connectWebView(selector = {}) {
+        const timeout = selector.timeout ?? this.capabilities.timeout;
+        const startedAt = Date.now();
+        let lastContexts = [];
+        while (Date.now() - startedAt <= timeout) {
+            const sockets = parseAndroidWebViewSockets(await this.adbText(['shell', 'cat', '/proc/net/unix']).catch(() => ''));
+            const candidates = selector.id
+                ? sockets.filter((socket) => socket === selector.id)
+                : sockets;
+            for (const socket of candidates) {
+                const port = await this.forwardWebView(socket);
+                const cdpUrl = `http://127.0.0.1:${port}`;
+                const targets = await readDevtoolsTargets(cdpUrl).catch(() => []);
+                if (!targets.length && matchesWebViewSelector({ id: socket, type: 'webview', socket }, selector)) {
+                    return {
+                        context: { id: socket, type: 'webview', socket },
+                        cdpUrl
+                    };
+                }
+                for (const target of targets) {
+                    const context = webViewContextFromTarget(socket, target);
+                    lastContexts.push(context);
+                    if (matchesWebViewSelector(context, selector)) {
+                        return {
+                            context,
+                            cdpUrl
+                        };
+                    }
+                }
+            }
+            await delay(500);
+        }
+        throw new AsturError('WEBVIEW_NOT_FOUND', 'No matching Android WebView context was available through DevTools.', {
+            selector,
+            contexts: lastContexts
+        });
+    }
+    async getKeyboardState() {
+        const command = await this.tryNativeCommand('keyboard.state');
+        if (command.ok) {
+            return command.result;
+        }
+        const output = await this.adbText(['shell', 'dumpsys', 'window']);
+        return parseAndroidKeyboardState(output);
+    }
+    async dismissKeyboard() {
+        const command = await this.tryNativeCommand('keyboard.dismiss');
+        if (command.ok) {
+            return;
+        }
+        if (!(await this.getKeyboardState()).visible) {
+            return;
+        }
+        await this.pressKey('BACK');
+        const deadline = Date.now() + 1_500;
+        while (Date.now() <= deadline) {
+            if (!(await this.getKeyboardState()).visible) {
+                return;
+            }
+            await delay(100);
+        }
+    }
+    async tryNativeCommand(method, params) {
+        if (!this.nativeAgent) {
+            return { ok: false };
+        }
+        if (this.unsupportedAgentMethods.has(method)) {
+            if (this.capabilities.agent.mode === 'required' || !allowsLegacyFallback(this.capabilities, 'unsupported')) {
+                throw new AsturError('ANDROID_AGENT_COMMAND_UNSUPPORTED', `Android native agent does not advertise support for ${method}.`, {
+                    endpoint: this.nativeAgent.endpoint,
+                    method,
+                    capabilities: this.nativeAgent.info.capabilities
+                });
+            }
+            return { ok: false };
+        }
+        if (!this.nativeAgent.info.capabilities.includes(method)) {
+            this.unsupportedAgentMethods.add(method);
+            if (this.capabilities.agent.mode === 'required' || !allowsLegacyFallback(this.capabilities, 'unsupported')) {
+                throw new AsturError('ANDROID_AGENT_COMMAND_UNSUPPORTED', `Android native agent does not advertise support for ${method}.`, {
+                    endpoint: this.nativeAgent.endpoint,
+                    method,
+                    capabilities: this.nativeAgent.info.capabilities
+                });
+            }
+            return { ok: false };
+        }
+        try {
+            const result = await this.nativeAgent.command(method, params);
+            return {
+                ok: true,
+                result
+            };
+        }
+        catch (error) {
+            if (isAgentCommandUnsupported(error)) {
+                this.unsupportedAgentMethods.add(method);
+                if (allowsLegacyFallback(this.capabilities, 'unsupported')) {
+                    return { ok: false };
+                }
+                throw new AsturError('ANDROID_AGENT_COMMAND_UNSUPPORTED', `Android native agent does not support ${method}.`, {
+                    endpoint: this.nativeAgent.endpoint,
+                    method,
+                    cause: error
+                });
+            }
+            if (isAgentCommandFailure(error)) {
+                if (allowsLegacyFallback(this.capabilities, 'failure')) {
+                    return { ok: false };
+                }
+                throw new AsturError('ANDROID_AGENT_COMMAND_FAILED', `Android native agent command ${method} failed.`, {
+                    endpoint: this.nativeAgent.endpoint,
+                    method,
+                    cause: error
+                });
+            }
+            this.nativeAgent = undefined;
+            if (!allowsLegacyFallback(this.capabilities, 'failure')) {
+                throw new AsturError('ANDROID_AGENT_COMMAND_FAILED', `Android native agent command ${method} failed.`, {
+                    method,
+                    cause: error
+                });
+            }
+            return { ok: false };
+        }
+    }
+    adb(args, maxBuffer) {
+        return run(this.adbPath, ['-s', this.deviceInfo.id, ...args], maxBuffer);
+    }
+    adbText(args) {
+        return runText(this.adbPath, ['-s', this.deviceInfo.id, ...args]);
+    }
+    async forwardWebView(socket) {
+        const output = await this.adbText(['forward', 'tcp:0', `localabstract:${socket}`]);
+        const port = Number(output.trim());
+        if (!Number.isInteger(port) || port <= 0) {
+            throw new AsturError('WEBVIEW_FORWARD_FAILED', `ADB did not return a TCP port for ${socket}.`, { output });
+        }
+        this.forwardedWebViewPorts.add(port);
+        return port;
+    }
+    resolvePackageName(app = this.capabilities.app) {
+        const packageName = app?.packageName ?? app?.bundleId;
+        if (!packageName) {
+            throw new AsturError('ANDROID_PACKAGE_REQUIRED', 'Android app management requires app.packageName.');
+        }
+        return packageName;
+    }
+}
+export function parseAdbDevices(output) {
+    return output
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line && !line.startsWith('List of devices'))
+        .map((line) => {
+        const [id, stateRaw, ...details] = line.split(/\s+/);
+        const detailMap = parseDetailTokens(details);
+        const model = detailMap.model?.replaceAll('_', ' ');
+        return {
+            id,
+            name: model ?? id,
+            platform: 'android',
+            kind: id.startsWith('emulator-') ? 'emulator' : 'real',
+            state: normalizeAdbState(stateRaw),
+            model,
+            raw: line
+        };
+    });
+}
+export function parseAaptBadging(output) {
+    const packageName = output.match(/package: name='([^']+)'/)?.[1];
+    if (!packageName) {
+        throw new AsturError('APK_PACKAGE_NOT_FOUND', 'Could not find package name in APK badging output.');
+    }
+    return {
+        packageName,
+        launchActivity: output.match(/launchable-activity: name='([^']+)'/)?.[1],
+        versionName: output.match(/versionName='([^']+)'/)?.[1]
+    };
+}
+export function parseAndroidKeyboardState(output) {
+    const imeSource = output.match(/InsetsSource id=.*? type=ime .*?(?=\n)/);
+    const imeSourceLine = imeSource?.[0] ?? '';
+    const visible = /\bvisible=true\b/.test(imeSourceLine) || /\bmImeShowing=true\b/.test(output);
+    if (!visible) {
+        return { visible: false };
+    }
+    const visibleFrame = imeSourceLine.match(/visibleFrame=(\[[^\]]+\]\[[^\]]+\])/);
+    const frame = imeSourceLine.match(/frame=(\[[^\]]+\]\[[^\]]+\])/);
+    const sourceFrame = output.match(/mSourceFrame=Rect\((\d+),\s*(\d+)\s*-\s*(\d+),\s*(\d+)\)/);
+    const bounds = parseAndroidWindowBounds(visibleFrame?.[1])
+        ?? parseAndroidWindowBounds(frame?.[1])
+        ?? (sourceFrame
+            ? rectToBounds(Number(sourceFrame[1]), Number(sourceFrame[2]), Number(sourceFrame[3]), Number(sourceFrame[4]))
+            : undefined);
+    return bounds ? { visible: true, bounds } : { visible: true };
+}
+export function parseAndroidLockState(output) {
+    return /\bshowing=true\b/.test(output)
+        || /\bmDreamingLockscreen=true\b/.test(output)
+        || /\bmInputRestricted=true\b/.test(output)
+        || /\bmAwake=false\b/.test(output)
+        || /\bmScreenOn(?:Early|Fully)?=false\b/.test(output);
+}
+export function parseAndroidWebViewSockets(output) {
+    const sockets = new Set();
+    const pattern = /@?((?:webview|chrome|content_shell)_devtools_remote(?:_[A-Za-z0-9_.-]+)?)/g;
+    let match;
+    while ((match = pattern.exec(output)) !== null) {
+        sockets.add(match[1]);
+    }
+    return [...sockets].sort();
+}
+export function parseAndroidLs(output, remotePath) {
+    return output
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line && !line.startsWith('total '))
+        .map((line) => parseAndroidLsLine(line, remotePath))
+        .filter((entry) => Boolean(entry));
+}
+function webViewContextFromTarget(socket, target) {
+    return {
+        id: target.id ? `${socket}:${target.id}` : socket,
+        type: 'webview',
+        title: target.title,
+        url: target.url,
+        socket,
+        pageId: target.id
+    };
+}
+function matchesWebViewSelector(context, selector) {
+    if (selector.id && selector.id !== context.id && selector.id !== context.socket && selector.id !== context.pageId) {
+        return false;
+    }
+    if (selector.packageName && selector.packageName !== context.packageName) {
+        return false;
+    }
+    if (selector.title && !matchesText(context.title, selector.title)) {
+        return false;
+    }
+    if (selector.url && !matchesText(context.url, selector.url)) {
+        return false;
+    }
+    return true;
+}
+function matchesText(actual, expected) {
+    if (!actual) {
+        return false;
+    }
+    return expected instanceof RegExp ? expected.test(actual) : actual.includes(expected);
+}
+function readDevtoolsTargets(cdpUrl) {
+    return new Promise((resolve, reject) => {
+        const request = httpGet(`${cdpUrl}/json/list`, (response) => {
+            const chunks = [];
+            response.on('data', (chunk) => {
+                chunks.push(chunk);
+            });
+            response.on('end', () => {
+                try {
+                    const body = Buffer.concat(chunks).toString('utf8');
+                    const parsed = JSON.parse(body);
+                    resolve(parsed.filter((target) => !target.type || target.type === 'page' || target.type === 'webview'));
+                }
+                catch (error) {
+                    reject(error);
+                }
+            });
+        });
+        request.on('error', reject);
+        request.setTimeout(3_000, () => {
+            request.destroy(new Error(`Timed out reading ${cdpUrl}/json/list`));
+        });
+    });
+}
+function selectDevice(devices, selector) {
+    return devices.find((device) => {
+        if (device.state !== 'online') {
+            return false;
+        }
+        if (selector.id && selector.id !== device.id) {
+            return false;
+        }
+        if (selector.kind && selector.kind !== device.kind) {
+            return false;
+        }
+        if (selector.name instanceof RegExp && !selector.name.test(device.name)) {
+            return false;
+        }
+        if (typeof selector.name === 'string' && selector.name !== device.name) {
+            return false;
+        }
+        return true;
+    });
+}
+function isElementSelectorTarget(target) {
+    return 'selector' in target;
+}
+function shouldAutoBoot(selector) {
+    return Boolean(selector.avd && selector.autoBoot !== false);
+}
+function resolveAndroidAgentArtifacts() {
+    const appApkPath = process.env.ASTUR_ANDROID_AGENT_APK
+        ?? resolveFirstExistingAndroidAgentArtifact('astur-android-agent-debug.apk', 'debug');
+    const testApkPath = process.env.ASTUR_ANDROID_AGENT_TEST_APK
+        ?? resolveFirstExistingAndroidAgentArtifact('astur-android-agent-debug-androidTest.apk', 'androidTest/debug');
+    if (!existsSync(appApkPath) || !existsSync(testApkPath)) {
+        return undefined;
+    }
+    return {
+        appApkPath,
+        testApkPath
+    };
+}
+function resolveFirstExistingAndroidAgentArtifact(fileName, variantPath) {
+    const androidPackageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+    const candidates = [
+        join(androidPackageRoot, 'assets', 'agent', fileName),
+        resolveDefaultAndroidAgentArtifact(fileName, variantPath)
+    ];
+    return candidates.find((candidate) => existsSync(candidate)) ?? candidates[0];
+}
+function resolveDefaultAndroidAgentArtifact(fileName, variantPath) {
+    const androidPackageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+    return join(androidPackageRoot, '..', 'android-agent', 'build', 'outputs', 'apk', variantPath, fileName);
+}
+function resolveAndroidAgentRuntimeConfig() {
+    return {
+        devicePort: parseOptionalPort(process.env.ASTUR_ANDROID_AGENT_DEVICE_PORT) ?? 8729,
+        hostPort: parseOptionalPort(process.env.ASTUR_ANDROID_AGENT_HOST_PORT),
+        packageName: process.env.ASTUR_ANDROID_AGENT_PACKAGE ?? 'dev.astur.agent',
+        testPackage: process.env.ASTUR_ANDROID_AGENT_TEST_PACKAGE ?? 'dev.astur.agent.test',
+        runnerClass: process.env.ASTUR_ANDROID_AGENT_RUNNER ?? 'dev.astur.agent.AsturInstrumentationRunner'
+    };
+}
+async function shouldInstallAndroidAgent(adb, config) {
+    if (isTruthy(process.env.ASTUR_ANDROID_AGENT_FORCE_INSTALL)) {
+        return true;
+    }
+    const [appInstalled, testInstalled] = await Promise.all([
+        isAndroidPackageInstalled(adb, config.packageName),
+        isAndroidPackageInstalled(adb, config.testPackage)
+    ]);
+    return !appInstalled || !testInstalled;
+}
+async function isAndroidPackageInstalled(adb, packageName) {
+    try {
+        const result = await adb(['shell', 'pm', 'path', packageName]);
+        return result.stdout.toString('utf8').trim().startsWith('package:');
+    }
+    catch {
+        return false;
+    }
+}
+function isTruthy(value) {
+    return value === '1' || value?.toLowerCase() === 'true' || value?.toLowerCase() === 'yes';
+}
+function androidRotationForOrientation(orientation) {
+    switch (orientation) {
+        case 'portrait':
+            return 0;
+        case 'landscape':
+        case 'landscape-left':
+            return 1;
+        case 'portrait-upside-down':
+            return 2;
+        case 'landscape-right':
+            return 3;
+    }
+}
+function normalizeAndroidPermission(permission) {
+    const value = permission.trim();
+    if (value.includes('.')) {
+        return value;
+    }
+    return `android.permission.${value.replace(/[\s-]+/g, '_').toUpperCase()}`;
+}
+function parseOptionalPort(value) {
+    if (!value) {
+        return undefined;
+    }
+    const port = Number(value);
+    if (!Number.isInteger(port) || port <= 0 || port > 65_535) {
+        throw new AsturError('ANDROID_AGENT_PORT_INVALID', `Invalid Android agent port: ${value}`);
+    }
+    return port;
+}
+function findFreePort() {
+    return new Promise((resolve, reject) => {
+        const server = createNetServer();
+        server.unref();
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', () => {
+            const address = server.address();
+            server.close(() => {
+                if (!address || typeof address === 'string') {
+                    reject(new AsturError('ANDROID_AGENT_PORT_UNAVAILABLE', 'Failed to allocate a host port for the Android agent.'));
+                    return;
+                }
+                resolve(address.port);
+            });
+        });
+    });
+}
+async function waitForAndroidAgent(endpoint, capabilities) {
+    const deadline = Date.now() + capabilities.agent.launchTimeout;
+    let lastError;
+    while (Date.now() <= deadline) {
+        try {
+            const remaining = Math.max(100, deadline - Date.now());
+            return await connectNativeAgentClient({
+                endpoint,
+                platform: 'android',
+                handshakeTimeout: Math.min(1_000, remaining),
+                commandTimeout: capabilities.agent.commandTimeout
+            });
+        }
+        catch (error) {
+            lastError = error;
+            await delay(250);
+        }
+    }
+    throw new AsturError('ANDROID_AGENT_CONNECT_FAILED', `Timed out waiting for Android native agent at ${endpoint}.`, {
+        endpoint,
+        timeout: capabilities.agent.launchTimeout,
+        cause: lastError
+    });
+}
+function resolveEmulatorPath() {
+    const executable = process.platform === 'win32' ? 'emulator.exe' : 'emulator';
+    const sdkRoot = process.env.ANDROID_HOME ?? process.env.ANDROID_SDK_ROOT;
+    if (sdkRoot) {
+        const candidate = join(sdkRoot, 'emulator', executable);
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    // Fall back to PATH lookup so an explicitly-configured emulator still works.
+    return executable;
+}
+function resolveAaptPath() {
+    const executable = process.platform === 'win32' ? 'aapt.exe' : 'aapt';
+    const sdkRoot = process.env.ANDROID_HOME ?? process.env.ANDROID_SDK_ROOT;
+    if (!sdkRoot) {
+        return undefined;
+    }
+    const buildToolsPath = join(sdkRoot, 'build-tools');
+    if (!existsSync(buildToolsPath)) {
+        return undefined;
+    }
+    const versions = readdirSync(buildToolsPath).sort((a, b) => b.localeCompare(a, undefined, { numeric: true }));
+    for (const version of versions) {
+        const candidate = join(buildToolsPath, version, executable);
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    return undefined;
+}
+function parseDetailTokens(tokens) {
+    const details = {};
+    for (const token of tokens) {
+        const index = token.indexOf(':');
+        if (index > 0) {
+            details[token.slice(0, index)] = token.slice(index + 1);
+        }
+    }
+    return details;
+}
+function parseAndroidWindowBounds(value) {
+    const match = value?.match(/\[(\d+),(\d+)\]\[(\d+),(\d+)\]/);
+    if (!match) {
+        return undefined;
+    }
+    return rectToBounds(Number(match[1]), Number(match[2]), Number(match[3]), Number(match[4]));
+}
+function rectToBounds(left, top, right, bottom) {
+    const width = right - left;
+    const height = bottom - top;
+    if (width <= 0 || height <= 0) {
+        return undefined;
+    }
+    return {
+        x: left,
+        y: top,
+        width,
+        height
+    };
+}
+function parseAndroidLsLine(line, remotePath) {
+    const parts = line.split(/\s+/);
+    if (parts.length < 8) {
+        return undefined;
+    }
+    const mode = parts[0];
+    const size = Number(parts[4]);
+    const name = parts.slice(7).join(' ');
+    if (!name || name === '.' || name === '..') {
+        return undefined;
+    }
+    return {
+        name,
+        path: joinRemotePath(remotePath, name),
+        type: mode.startsWith('d') ? 'directory' : mode.startsWith('-') ? 'file' : 'other',
+        size: Number.isFinite(size) ? size : undefined
+    };
+}
+function joinRemotePath(remotePath, name) {
+    return `${remotePath.replace(/\/+$/, '')}/${name}`;
+}
+function waitForProcessExit(child, timeout) {
+    return new Promise((resolve) => {
+        if (child.exitCode !== null || child.killed) {
+            resolve();
+            return;
+        }
+        const timer = setTimeout(() => {
+            child.kill('SIGKILL');
+            resolve();
+        }, timeout);
+        child.once('exit', () => {
+            clearTimeout(timer);
+            resolve();
+        });
+    });
+}
+export function normalizeAndroidKey(key) {
+    const normalized = key.trim().toUpperCase().replace(/[\s-]+/g, '_');
+    const aliases = {
+        APP_SWITCH: 'KEYCODE_APP_SWITCH',
+        BACK: 'KEYCODE_BACK',
+        ENTER: 'KEYCODE_ENTER',
+        HOME: 'KEYCODE_HOME',
+        MENU: 'KEYCODE_MENU',
+        POWER: 'KEYCODE_POWER',
+        RECENT_APPS: 'KEYCODE_APP_SWITCH',
+        RECENTS: 'KEYCODE_APP_SWITCH',
+        SEARCH: 'KEYCODE_SEARCH',
+        SLEEP: 'KEYCODE_SLEEP',
+        TAB: 'KEYCODE_TAB',
+        WAKEUP: 'KEYCODE_WAKEUP',
+        VOLUME_DOWN: 'KEYCODE_VOLUME_DOWN',
+        VOLUME_UP: 'KEYCODE_VOLUME_UP'
+    };
+    return aliases[normalized] ?? (normalized.startsWith('KEYCODE_') ? normalized : key);
+}
+function normalizeAdbState(state) {
+    if (state === 'device') {
+        return 'online';
+    }
+    if (state === 'offline' || state === 'unauthorized') {
+        return state;
+    }
+    return 'unknown';
+}
+function escapeAndroidInputText(value) {
+    return value.replaceAll('%', '%25').replace(/\s/g, '%s');
+}
+function firstLine(value) {
+    return value.split(/\r?\n/).find(Boolean) ?? value.trim();
+}
+function warnAndroidAgentFallback(message) {
+    if (process.env.ASTUR_ANDROID_AGENT_QUIET === '1') {
+        return;
+    }
+    console.warn(`[astur/android] ${message}`);
+}
+function isAgentCommandUnsupported(error) {
+    if (!(error instanceof AsturError)) {
+        return false;
+    }
+    return error.code === 'NOT_IMPLEMENTED' || error.code === 'UNKNOWN_COMMAND';
+}
+function isAgentCommandFailure(error) {
+    if (!(error instanceof AsturError)) {
+        return false;
+    }
+    return !isAgentTransportFailure(error);
+}
+function isAgentTransportFailure(error) {
+    return error.code.startsWith('AGENT_') && !isAgentCommandUnsupported(error);
+}
+function allowsLegacyFallback(capabilities, reason) {
+    if (capabilities.agent.mode === 'required') {
+        return false;
+    }
+    switch (capabilities.agent.legacyFallback) {
+        case 'never':
+            return false;
+        case 'on-unsupported-command':
+            return reason === 'unsupported';
+        case 'on-agent-failure':
+            return true;
+    }
+}
+//# sourceMappingURL=index.js.map