prompttest 1.3.0

package/dist/lib/crawler.d.ts

@@ -0,0 +1,335 @@
+/**
+ * @module Crawler
+ * Parses Android uiautomator XML hierarchy dumps into structured node trees
+ * and provides element filtering, detection functions, and visual defect scanning.
+ * This module is crucial for interpreting the device screen state.
+ */
+/**
+ * Represents the rectangular bounds of a UI element on the screen.
+ */
+export interface ElementBounds {
+    /** The x-coordinate of the left edge */
+    x1: number;
+    /** The y-coordinate of the top edge */
+    y1: number;
+    /** The x-coordinate of the right edge */
+    x2: number;
+    /** The y-coordinate of the bottom edge */
+    y2: number;
+    /** The width of the element */
+    width: number;
+    /** The height of the element */
+    height: number;
+    /** The x-coordinate of the center point */
+    centerX: number;
+    /** The y-coordinate of the center point */
+    centerY: number;
+}
+/**
+ * Represents a parsed node from the uiautomator XML hierarchy.
+ */
+export interface UiNode {
+    /** The index of the node among its siblings */
+    index: number;
+    /** The text content of the element */
+    text: string;
+    /** The Android resource ID of the element */
+    resourceId: string;
+    /** The Android class name of the element (e.g., android.widget.TextView) */
+    className: string;
+    /** The package name of the app the element belongs to */
+    packageName: string;
+    /** The content description (accessibility text) of the element */
+    contentDesc: string;
+    /** The physical bounds of the element on screen */
+    bounds: ElementBounds;
+    /** Whether the element can be clicked */
+    clickable: boolean;
+    /** Whether the element is currently enabled */
+    enabled: boolean;
+    /** Whether the element currently has input focus */
+    focused: boolean;
+    /** Whether the element can be scrolled */
+    scrollable: boolean;
+    /** Whether the element is a password field */
+    password: boolean;
+    /** Whether the element is selected */
+    selected: boolean;
+    /** Whether the element is currently checked (if applicable) */
+    checked?: boolean;
+    /** Whether the element can be checked */
+    checkable?: boolean;
+    /** The child nodes nested within this element */
+    children: UiNode[];
+}
+/**
+ * Criteria for filtering and selecting specific UI nodes.
+ */
+export interface ElementSelector {
+    /** Exact text or regular expression to match element text */
+    text?: string | RegExp;
+    /** Exact string or regular expression to match resource ID */
+    resourceId?: string | RegExp;
+    /** Exact string or regular expression to match content description */
+    contentDesc?: string | RegExp;
+    /** Substring to match within the class name */
+    className?: string;
+    /** Require the element to be clickable (true) or not clickable (false) */
+    clickable?: boolean;
+}
+/**
+ * Parses a raw bounds string (e.g., "[0,0][1080,2400]") into an ElementBounds object.
+ *
+ * @param {string} raw - The bounds string from the XML attribute.
+ * @returns {ElementBounds} The parsed bounding box and center coordinates.
+ */
+export declare function parseBounds(raw: string): ElementBounds;
+/**
+ * Parses raw uiautomator XML dump into a tree of structured UI nodes.
+ *
+ * @param {string} xmlContent - The raw XML string from the device.
+ * @returns {{ root: UiNode[]; flat: UiNode[] }} An object containing the root nodes and a flattened list of all nodes.
+/**
+ * Regex-based tag stack machine parsing uiautomator XML.
+ * Simulates an XML parser using a regex loop to build the tree manually.
+ *
+ * @param xmlContent The raw XML string from the device.
+ * @returns Object containing root nodes and a flattened list of all nodes.
+ */
+export declare function parseHierarchyXmlRegex(xmlContent: string): {
+    root: UiNode[];
+    flat: UiNode[];
+};
+/**
+ * Streaming SAX-style parser for uiautomator XML dumps (SP-05).
+ * Tokenizes character-by-character so attribute values containing '>' or '<'
+ * cannot corrupt tag parsing or tree structure.
+ *
+ * @param xmlContent The raw XML string.
+ * @returns Object containing root nodes and a flattened list of all nodes.
+ */
+export declare function parseHierarchyXmlStreaming(xmlContent: string): {
+    root: UiNode[];
+    flat: UiNode[];
+};
+/**
+ * Parses raw uiautomator XML dump into a tree of structured UI nodes.
+ * Supports configurable parser mode ('regex' | 'streaming') (SP-05).
+ *
+ * @param xmlContent The raw XML string from the device.
+ * @param mode Optional parser mode override ('regex' | 'streaming'). Defaults to CONFIG.parser.mode.
+ * @returns An object containing the root nodes and a flattened list of all nodes.
+ */
+export declare function parseHierarchyXml(xmlContent: string, mode?: 'regex' | 'streaming'): {
+    root: UiNode[];
+    flat: UiNode[];
+};
+/**
+ * Filters a list of UI nodes based on the given element selector criteria.
+ *
+ * @param {UiNode[]} nodes - The array of UI nodes to filter.
+ * @param {ElementSelector} selector - The criteria to apply for filtering.
+ * @returns {UiNode[]} An array of nodes that match the selector criteria.
+ */
+export declare function findNodes(nodes: UiNode[], selector: ElementSelector): UiNode[];
+/**
+ * Patterns identifying development error, warning, info consoles, toasts, and stack traces.
+ */
+export declare const LOGBOX_PATTERNS: readonly RegExp[];
+/**
+ * Evaluates whether a UI element belongs to a development overlay, LogBox console, or stack trace.
+ *
+ * @param node - UI element node to inspect.
+ * @returns True if element is part of a development console or overlay.
+ */
+export declare function isLogBoxNode(node: UiNode): boolean;
+/**
+ * Finds text input fields (EditText / TextInput) on screen.
+ *
+ * @param {UiNode[]} nodes - The array of UI nodes to search within.
+ * @returns {UiNode[]} A list of input field nodes.
+ */
+export declare function findInputFields(nodes: UiNode[]): UiNode[];
+/**
+ * Detects items inside scrollable lists / RecyclerViews / ListViews.
+ *
+ * @param {UiNode[]} nodes - The array of UI nodes to search within.
+ * @param {{ width: number; height: number }} [screenDims] - Optional screen dimensions to scale heuristics against.
+ * @returns {UiNode[]} A list of nodes that represent individual items in a list.
+ */
+export declare function findListItems(nodes: UiNode[], screenDims?: {
+    width: number;
+    height: number;
+}): UiNode[];
+/**
+ * Finds interactive action buttons on screen (e.g. Save, Submit, Like, Favorite, Add, Sign In).
+ *
+ * @param {UiNode[]} nodes - The array of UI nodes to search within.
+ * @returns {UiNode[]} A list of action button nodes.
+ */
+export declare function findActionButtons(nodes: UiNode[]): UiNode[];
+/**
+ * Finds bottom navigation tabs or tab layout items.
+ *
+ * @param {UiNode[]} nodes - The array of UI nodes to search within.
+ * @param {number} [screenHeight=CONFIG.screen.fallbackHeight] - The height of the screen to calculate the bottom threshold.
+ * @returns {UiNode[]} A list of navigation tab nodes.
+ */
+export declare function findNavigationTabs(nodes: UiNode[], screenHeight?: number, targetPackage?: string): UiNode[];
+/**
+ * Checks for visible crash messages, error dialogs, or ANRs.
+ *
+ * @param {UiNode[]} nodes - The array of UI nodes to search within.
+ * @returns {UiNode[]} A list of nodes that appear to be part of an error or crash dialog.
+ */
+export declare function findErrorDialogs(nodes: UiNode[]): UiNode[];
+/**
+ * Patterns that indicate potentially irreversible or high-risk destructive actions.
+ * Autonomous exploration must never tap elements matching these patterns in strict mode.
+ */
+export declare const DESTRUCTIVE_ACTION_PATTERNS: readonly RegExp[];
+/**
+ * Moderate safety patterns shielding solely authentication and catastrophic account loss,
+ * while permitting localized in-app modifications and draft/item deletions.
+ */
+export declare const MODERATE_DESTRUCTIVE_PATTERNS: readonly RegExp[];
+/**
+ * Patterns identifying external app triggers, deep links, or web views (AX-11).
+ * Autonomous crawlers skip these in-app to prevent escaping into Chrome, Play Store, or external apps.
+ */
+export declare const EXTERNAL_INTENT_PATTERNS: readonly RegExp[];
+/**
+ * Supported safety enforcement policies (AX-10).
+ */
+export type SafetyMode = 'strict' | 'moderate' | 'interactive' | 'disabled';
+/**
+ * Evaluates whether a UI element represents a destructive or high-risk action (AX-09, AX-10).
+ *
+ * @param node - UI element node to inspect.
+ * @param customBlacklist - Optional user-defined keywords or regular expressions.
+ * @param mode - Safety enforcement mode ('strict', 'moderate', 'interactive', 'disabled').
+ * @returns True if the element matches destructive patterns under the active safety policy.
+ */
+export declare function isDestructiveAction(node: UiNode, customBlacklist?: readonly (string | RegExp)[], mode?: SafetyMode): boolean;
+/**
+ * Evaluates whether a UI element represents an external app intent or web link (AX-11).
+ *
+ * @param node - UI element node to inspect.
+ * @returns True if element matches external intent patterns.
+ */
+export declare function isExternalIntentAction(node: UiNode): boolean;
+/**
+ * Information describing a detected development console or modal overlay (AX-13).
+ */
+/**
+ * Information describing a detected development console or modal overlay (AX-13).
+ */
+export interface DevOverlayMatch {
+    type: 'logbox' | 'anr';
+    severity: 'error' | 'warning' | 'info';
+    node: UiNode;
+    errorText: string;
+    sourceLocation?: string;
+    stackTrace?: string[];
+    dismissButton?: UiNode;
+    isToast?: boolean;
+}
+/**
+ * Scans UI hierarchy nodes to detect development error consoles, LogBox overlays, warnings, info toasts, or ANRs (AX-13).
+ *
+ * @param nodes - Array of UI nodes on the current screen.
+ * @returns Match metadata if an overlay is detected, otherwise null.
+ */
+export declare function findDevOverlay(nodes: UiNode[]): DevOverlayMatch | null;
+/**
+ * Identifies toggleable controls such as checkboxes, switches, and radio buttons.
+ *
+ * @param nodes - Array of UI nodes.
+ * @returns Array of checkable or switch UI nodes.
+ */
+export declare function findCheckableControls(nodes: UiNode[]): UiNode[];
+/**
+ * Detects side-drawer or hamburger navigation buttons (AX-03).
+ *
+ * @param nodes - Array of UI nodes on the current screen.
+ * @param screenHeight - Screen height used to bound top navigation bar area.
+ * @returns The drawer button node, or null if none is present.
+ */
+export declare function findDrawerButton(nodes: UiNode[], screenHeight?: number, screenWidth?: number): UiNode | null;
+/**
+ * Finds top-right header action buttons (e.g. Notification bell, Search, Settings, More options).
+ */
+export declare function findHeaderActionButtons(nodes: UiNode[], screenHeight?: number, screenWidth?: number): UiNode[];
+/**
+ * Identifies vertically scrollable containers on screen (AX-04).
+ * (e.g. ScrollView, RecyclerView, ListView, or nodes with scrollable: true).
+ *
+ * @param nodes - Array of UI nodes.
+ * @returns Array of scrollable container nodes.
+ */
+export declare function findScrollableContainers(nodes: UiNode[]): UiNode[];
+/**
+ * Represents a detected visual defect on the screen, such as overflows or overlapping text.
+ */
+export interface VisualDefect {
+    /** The type or category of the visual defect */
+    type: 'OVERLAP' | 'OVERFLOW' | 'STALLED_LOADER';
+    /** The severity level of the defect */
+    severity: 'WARN' | 'ERROR';
+    /** A human-readable description of what is wrong */
+    description: string;
+    /** The identifiers of the UI elements involved in the defect */
+    elements: string[];
+}
+/**
+ * Inspects parsed UI hierarchy to detect visual bugs, broken layouts,
+ * clipped elements, and unintended overlapping text nodes.
+ *
+ * @param {UiNode[]} nodes - The array of structured UI nodes representing the current screen.
+ * @param {number} [screenWidth=1080] - The physical width of the device screen.
+ * @param {number} [screenHeight=2400] - The physical height of the device screen.
+ * @returns {VisualDefect[]} A list of any detected visual anomalies or bugs.
+ */
+export declare function detectVisualDefects(nodes: UiNode[], screenWidth?: number, screenHeight?: number, overlapRatio?: number): VisualDefect[];
+/**
+ * Navigation paradigm detected for an application.
+ */
+export type NavigationParadigm = 'bottom_tabs' | 'top_tabs' | 'drawer' | 'single_hub';
+/**
+ * Result of detecting the top-level navigation structure.
+ */
+export interface NavigationParadigmResult {
+    paradigm: NavigationParadigm;
+    roots: UiNode[];
+}
+/**
+ * Detects the root navigation paradigm of an application (Universal Navigation).
+ *
+ * @param nodes - Array of UI nodes on the screen.
+ * @param screenDims - Physical screen width and height.
+ * @param targetPackage - Optional package name filter.
+ * @returns Detected paradigm and list of root interactive elements.
+ */
+export declare function detectNavigationParadigm(nodes: UiNode[], screenDims?: {
+    width: number;
+    height: number;
+}, targetPackage?: string): NavigationParadigmResult;
+/**
+ * Partitions repeated sibling cards/list items into equivalence classes,
+ * keeping at most maxPerCluster representative items per family (Universal List Guard).
+ *
+ * @param nodes - Array of candidate list items.
+ * @param maxPerCluster - Maximum items to keep per sibling group (default: 2).
+ * @returns Pruned list with representative items.
+ */
+export declare function clusterSiblingElements(nodes: UiNode[], maxPerCluster?: number): UiNode[];
+/**
+ * Locates an in-app Back, Close, or Cancel button in the upper screen area (Universal Backtracking).
+ *
+ * @param nodes - Array of UI nodes on the current screen.
+ * @param screenHeight - Screen height used to bound top bar area.
+ * @param screenWidth - Screen width used to bound top-left area.
+ * @param isChildScreen - Whether we are currently in an inner/child screen where top-left icon is a back button.
+ * @returns The in-app back button node, or null if none found.
+ */
+export declare function findInAppBackButton(nodes: UiNode[], screenHeight?: number, screenWidth?: number, isChildScreen?: boolean): UiNode | null;

package/dist/lib/data-loader.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @module data-loader
+ * @description Data-driven test provider for PromptTest.
+ * Parses external CSV/JSON files and inline data directives (#!data),
+ * providing parameter rows for multi-iteration test execution.
+ */
+export interface DataFilterOptions {
+    onlyRow?: number;
+    iterations?: number;
+}
+export interface ParsedDataDirective {
+    /** Raw directive string found in spec header. */
+    directive: string;
+    /** File path referenced in #!data directive, or 'inline'. */
+    source: string;
+    /** Cleaned spec text with data directives removed. */
+    cleanedSpec: string;
+    /** Parsed data rows. */
+    rows: Record<string, string>[];
+}
+export declare class DataSpecLoader {
+    /**
+     * Discovers and parses `#!data` directive in spec content.
+     *
+     * @param specContent - Raw spec content.
+     * @param baseDir - Directory of the spec file to resolve relative paths.
+     * @returns Parsed directive details and rows, or null if no #!data directive exists.
+     */
+    static extractDataDirective(specContent: string, baseDir?: string): ParsedDataDirective | null;
+    /**
+     * Loads data rows from an external CSV or JSON file.
+     *
+     * @param filePath - Path to CSV or JSON data file.
+     * @returns Array of key-value data records.
+     */
+    static loadFromFile(filePath: string): Record<string, string>[];
+    /**
+     * Parses JSON string into an array of string-mapped records.
+     */
+    static parseJson(jsonString: string): Record<string, string>[];
+    /**
+     * Robust RFC-4180 compliant CSV parser supporting quotes, commas within fields,
+     * escaped quotes (""), and varied newline formats.
+     */
+    static parseCsv(csvString: string): Record<string, string>[];
+    /**
+     * Filters and bounds rows according to CLI / execution flags (e.g. onlyRow, iterations).
+     */
+    static filterRows(rows: Record<string, string>[], options?: DataFilterOptions): Record<string, string>[];
+    private static parseCsvRow;
+    private static splitCsvLines;
+    private static stringifyObject;
+}

package/dist/lib/dfs-engine.d.ts

@@ -0,0 +1,106 @@
+import type { UiNode } from './crawler.js';
+import { type SafetyMode } from './crawler.js';
+import { AndroidDriver } from './adb.js';
+import { QaReporter } from './reporter.js';
+import { MemoryEngine } from './memory.js';
+export interface DfsElementAction {
+    node: UiNode;
+    type: 'input' | 'toggle' | 'overlay' | 'transition';
+    label: string;
+    tested: boolean;
+}
+export interface ScreenNode {
+    hash: string;
+    semanticHash: string;
+    title: string;
+    elements: DfsElementAction[];
+    status: 'DISCOVERED' | 'IN_PROGRESS' | 'FULLY_EXPLORED';
+    depth: number;
+    interactionCount: number;
+}
+export interface NavigationFrame {
+    screenHash: string;
+    semanticHash: string;
+    title: string;
+    actionTaken?: string;
+    timestamp: number;
+}
+export interface DfsEngineOptions {
+    packageName: string;
+    serial?: string;
+    maxScreens?: number;
+    maxDepth?: number;
+    stepBudget?: number;
+    maxInteractionsPerScreen?: number;
+    safetyMode?: SafetyMode;
+    safetyBlacklist?: readonly (string | RegExp)[];
+    screenshotPolicy?: 'all' | 'state-change' | 'failure-only';
+    skipAlreadyCrawled?: boolean;
+}
+/**
+ * Universal Hierarchical State-Graph DFS Engine (Universal Exploration Engine).
+ * Explores mobile applications systematically by root navigation domains,
+ * maintaining a call stack with cycle detection, multi-strategy backtracking,
+ * in-place prioritization, and canonical semantic state hashing.
+ */
+export declare class HierarchicalDfsEngine {
+    private driver;
+    private reporter;
+    private memory;
+    private formFiller;
+    screenLedger: Map<string, ScreenNode>;
+    callStack: NavigationFrame[];
+    executedStepCount: number;
+    visitedScreenHashes: Set<string>;
+    devDefectsList: string[];
+    safetyHitList: string[];
+    externalSkippedList: string[];
+    constructor(driver?: AndroidDriver, reporter?: QaReporter, memory?: MemoryEngine);
+    /**
+     * Captures UI hierarchy globally, intercepting and triaging any development error consoles,
+     * LogBox overlays, warnings, info toasts, or ANRs before returning a clean app hierarchy.
+     */
+    getCleanUiHierarchy(packageName: string, serial?: string, maxTriageAttempts?: number): Promise<{
+        xml: string;
+        flat: UiNode[];
+    }>;
+    /**
+     * Automatically lowers the on-screen soft keyboard after typing.
+     */
+    dismissSoftKeyboard(serial?: string): Promise<void>;
+    /**
+     * Verifies app is running in foreground; recovers if it escaped into third-party apps.
+     */
+    packageJailGuard(packageName: string, serial?: string): Promise<boolean>;
+    /**
+     * Detects and dismisses system app choosers ("Open with" / ResolverActivity)
+     * to ensure playback remains strictly in-app.
+     */
+    handleExternalMediaChooser(packageName: string, serial?: string): Promise<boolean>;
+    /**
+     * Catalogs all interactive elements on a screen and classifies them into:
+     * 1. In-place input/search fields
+     * 2. In-place toggle/checkbox controls
+     * 3. Ephemeral modals/pickers
+     * 4. Deep navigational transitions (action buttons, list cards)
+     */
+    catalogScreen(nodes: UiNode[], screenDims: {
+        width: number;
+        height: number;
+    }, rootNodes?: UiNode[]): DfsElementAction[];
+    /**
+     * Multi-strategy universal backtracking:
+     * 1. Try explicit in-app back/close button in upper screen
+     * 2. Try hardware KEYCODE_BACK
+     * 3. Verify parent restoration
+     */
+    safeBacktrack(expectedSemanticHash: string, packageName: string, serial?: string, rootNode?: UiNode, allowHardwareBack?: boolean): Promise<boolean>;
+    /**
+     * Executes universal Hierarchical State-Graph DFS exploration.
+     */
+    explore(options: DfsEngineOptions): Promise<void>;
+    /**
+     * Recursive/Stack-based DFS node explorer for a given screen.
+     */
+    private exploreDfsNode;
+}

package/dist/lib/dictionary.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Curated Universal Mobile UI Seed Dictionary.
+ * Maps canonical English concepts to standard mobile synonyms, icon glyphs,
+ * accessibility labels, and component naming conventions.
+ *
+ * Schema: Record<CanonicalTerm, Array<Synonym>>
+ * Usage: Used to pre-populate the memory engine and enhance naive semantic
+ * string matching during UI hierarchy traversal.
+ */
+/**
+ * Curated Universal Mobile UI Seed Dictionary Packs per Locale.
+ * Maps canonical concepts to standard mobile synonyms, icon glyphs,
+ * accessibility labels, and component naming conventions.
+ */
+export declare const LOCALE_PACKS: Record<string, Record<string, string[]>>;
+/**
+ * Backward compatibility export: Canonical English mobile taxonomy.
+ */
+export declare const GLOBAL_SEED_DICTIONARY: Record<string, string[]>;
+/**
+ * Registers or extends a custom locale pack at runtime.
+ *
+ * @param locale Two-letter or language code (e.g. 'fr', 'de', 'ja').
+ * @param pack Record mapping canonical concepts to synonyms.
+ */
+export declare function registerLocalePack(locale: string, pack: Record<string, string[]>): void;
+/**
+ * Returns list of all registered locale identifiers.
+ */
+export declare function getSupportedLocales(): string[];
+/**
+ * Returns canonical synonyms for a given term from the locale seed dictionary in O(1) time.
+ * Falls back to English if term is not found in specified locale.
+ *
+ * @param term The word or phrase to look up.
+ * @param locale Optional locale code. Defaults to 'en'.
+ * @returns An array of normalized synonyms, including the original term itself.
+ */
+export declare function getSeedSynonyms(term: string, locale?: string): string[];
+/** Alias for getSeedSynonyms */
+export declare const getSynonyms: typeof getSeedSynonyms;

package/dist/lib/doctor.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @module doctor
+ * @description
+ * Diagnostic health check utility for PromptTest.
+ * Validates the local developer environment, Node.js version, ADB installation,
+ * device connectivity, authorization, filesystem permissions, and target package availability.
+ */
+import { AndroidDriver } from './adb.js';
+export interface DoctorCheck {
+    name: string;
+    passed: boolean;
+    message: string;
+    hint?: string;
+    details?: Record<string, unknown>;
+}
+export interface DoctorReport {
+    timestamp: string;
+    allPassed: boolean;
+    checks: DoctorCheck[];
+    summary: {
+        passed: number;
+        failed: number;
+        warnings: number;
+    };
+}
+export interface DoctorOptions {
+    packageName?: string;
+    serial?: string;
+    json?: boolean;
+}
+/**
+ * Runs a complete diagnostic scan of the PromptTest environment.
+ *
+ * @param driver - The AndroidDriver instance to query.
+ * @param options - Diagnostic scan configuration options.
+ * @returns Complete DoctorReport.
+ */
+export declare function runDoctor(driver?: AndroidDriver, options?: DoctorOptions): Promise<DoctorReport>;
+/**
+ * Formats a DoctorReport into user-friendly CLI terminal output with icons and remediation hints.
+ *
+ * @param report - The DoctorReport to format.
+ * @returns Multi-line formatted terminal string.
+ */
+export declare function formatDoctorReport(report: DoctorReport): string;

package/dist/lib/driver-interface.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @module driver-interface
+ * @description
+ * Universal mobile device driver interface and common types for PromptTest.
+ * Decouples the test runner and autonomous crawler from platform-specific APIs
+ * (Android ADB vs. iOS XCUITest / simctl / idb).
+ */
+export interface MobileDeviceInfo {
+    serial: string;
+    state: 'device' | 'simulator' | 'offline' | 'unauthorized';
+    model?: string;
+    platform: 'android' | 'ios';
+}
+export interface ScreenDimensions {
+    width: number;
+    height: number;
+}
+/**
+ * Common device driver contract implemented by AndroidDriver and IosDriver.
+ */
+export interface DeviceDriver {
+    /** Returns the primary target device serial or identifier. */
+    getDefaultDevice(): string | undefined;
+    /** Resolves or validates the active device identifier. */
+    ensureDefaultDevice(serial?: string): Promise<string>;
+    /** Lists all connected physical devices and emulators/simulators. */
+    getConnectedDevices(): Promise<MobileDeviceInfo[]>;
+    /** Retrieves the screen resolution in physical pixels. */
+    getScreenDimensions(serial?: string): Promise<ScreenDimensions>;
+    /** Captures the current display buffer as a PNG image. */
+    captureScreenshot(serial?: string): Promise<Buffer>;
+    /** Dumps the active window accessibility UI hierarchy XML. */
+    getUiHierarchy(serial?: string): Promise<string>;
+    /** Simulates a touch tap gesture at coordinates (x, y). */
+    tap(x: number, y: number, serial?: string): Promise<void>;
+    /** Simulates typing text into the currently focused input field. */
+    inputText(text: string, serial?: string): Promise<void>;
+    /** Sends a key event or hardware keycode. */
+    pressKey(key: string, serial?: string): Promise<void>;
+    /** Performs a touch drag or swipe gesture between two points. */
+    swipe(x1: number, y1: number, x2: number, y2: number, durationMs?: number, serial?: string): Promise<void>;
+    /** Launches an application by package name (Android) or bundle ID (iOS). */
+    launchApp(appId: string, serial?: string): Promise<void>;
+    /** Forcefully terminates a running application. */
+    forceStop(appId: string, serial?: string): Promise<void>;
+    /** Checks if the application is installed on the target device. */
+    isAppInstalled(appId: string, serial?: string): Promise<boolean>;
+    /** Retrieves the foreground active package name or bundle ID. */
+    getForegroundPackage(serial?: string): Promise<string | null>;
+}