shellx-ai 1.1.0 → 1.1.1

package/README.md

@@ -2,585 +2,665 @@
 
 <div align="center">
 
-  **A powerful TypeScript library for Android device automation and UI control**
+  **TypeScript library for Android device automation via WebSocket**
 
   [![npm version](https://badge.fury.io/js/shellx-ai.svg)](https://www.npmjs.org/package/shellx-ai)
   [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
   [![Node.js Version](https://img.shields.io/node/v/shellx-ai.svg)](https://nodejs.org)
   [![TypeScript](https://img.shields.io/badge/TypeScript-5.8-blue.svg)](https://www.typescriptlang.org/)
-  [![Code Style](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://prettier.io)
 
-  [Features](#-features) • [Quick Start](#-quick-start) • [API Guide](#-api-guide) • [API Reference](#-api-reference) • [Examples](#-examples) • [Contributing](#-contributing)
+  [Features](#-features) • [Installation](#-installation) • [Quick Start](#-quick-start) • [API Reference](#-api-reference) • [Examples](#-examples)
 
 </div>
 
 ---
 
-## 🎯 Which API Should I Use?
+## Summary
 
-ShellX provides two API levels. Choose the one that matches your needs:
+ShellX AI is a TypeScript library that enables programmatic control of Android devices through a WebSocket connection. It provides a simple, type-safe API for:
 
-### 🟢 ShellX (High-Level API) - **Recommended for 95% of users**
+- **UI Automation** - Click, input, swipe, press keys, wait for elements
+- **Element Finding** - Find UI elements by text, ID, class, or coordinates
+- **Shell Commands** - Execute shell commands and get output
+- **Device Info** - Get screen info, app info, screenshots
+- **Batch Operations** - Execute multiple actions in sequence
 
-Perfect for most automation tasks:
-- ✅ Simple, intuitive methods
-- ✅ Automatic error handling & retry
-- ✅ Type-safe with TypeScript
-- ✅ Less code to write
-
-```typescript
-import { ShellX } from 'shellx-ai';
-
-const shellx = new ShellX({ deviceId: 'your-device-id' });
-await shellx.connect();
-
-// Easy to use!
-await shellx.click('Submit');
-await shellx.input({ text: 'Hello World' });
-await shellx.swipe({ fromX: 500, fromY: 1000, toX: 500, toY: 500 });
-```
-
-### 🔵 ConnectionClient (Low-Level API) - Advanced users only
+---
 
-For special cases requiring direct WebSocket access:
-- Custom protocol implementations
-- Debugging WebSocket communication
-- Non-standard operations
+## Features
 
-**⚠️ Warning:** Steeper learning curve. Most users don't need this.
+- 🎯 **Simple API** - Intuitive methods for common automation tasks
+- 🔄 **Auto Retry** - Built-in retry logic for robust operations
+- 📝 **Type-Safe** - Full TypeScript support with comprehensive types
+- 🌍 **Cross-Platform** - Works in Node.js and browser environments
+- 📸 **Screenshots** - Capture screenshots with customizable options
+- 🔧 **Shell Commands** - Execute commands with real-time output
+- 🛠️ **Batch Actions** - Chain multiple operations together
 
-```typescript
-import { ConnectionClient } from 'shellx-ai';
+---
 
-const client = new ConnectionClient('device-id');
-await client.ensureConnected();
+## Installation
 
-// Low-level protocol access
-await client.sendMessage({ click: { elementId: 'element123' } });
+```bash
+npm install shellx-ai
 ```
 
-**📚 See [API-GUIDE.md](./API-GUIDE.md) for detailed comparison and examples.**
-
----
-
-## ✨ Features
+### Requirements
 
-ShellX AI provides a comprehensive suite of tools for Android device automation:
+- Node.js >= 14.0.0
+- TypeScript >= 4.0.0 (recommended)
+- Android device connected to ShellX service
 
-- 🎯 **Smart UI Automation** - Advanced element finding with retry logic and multiple selector strategies
-- 🔧 **Shell Command Execution** - Execute shell commands with real-time output monitoring
-- 📸 **Screen Operations** - Screenshots, screen info, and visual element capture
-- 🔄 **Automatic Retry Logic** - Built-in retry mechanism for robust operations
-- 🛠️ **Modular Architecture** - Clean, maintainable code structure with separation of concerns
-- 📝 **Type-Safe API** - Full TypeScript support with comprehensive type definitions
-- 🌍 **Global Optimization** - Automatic domain selection based on user location
-- 🧪 **Well-Tested** - Comprehensive test coverage for reliability
+### Optional Dependencies
 
-## 📦 Installation
+For Node.js environment, install ws:
 
 ```bash
-npm install shellx-ai
+npm install ws  # Optional, for Node.js WebSocket support
 ```
 
-### Requirements
+For browser environments, no additional dependencies needed.
 
-- **Node.js**: >= 14.0.0
-- **TypeScript**: >= 4.0.0 (recommended)
+---
 
-## 🚀 Quick Start
+## Quick Start
 
-### Basic Usage
+### 1. Basic Example
 
 ```typescript
 import { ShellX } from 'shellx-ai';
 
 // Create ShellX instance
 const shellx = new ShellX({
-  deviceId: 'your-device-id',
-  onOpen: () => console.log('Connected!'),
-  onMessage: (message) => console.log('Message:', message)
+  deviceId: 'your-device-id'  // Replace with your device ID
 });
 
-// Wait for connection to be ready
+// Wait for connection
 await shellx.ready();
 
+// Click element by text
+await shellx.click('Settings');
+
+// Get screen info
+const screen = await shellx.getScreenInfo();
+console.log(`Screen: ${screen.width}x${screen.height}`);
+
 // Execute shell command
-const result = await shellx.command({ cmd: 'getprop ro.build.version.release' });
+const result = await shellx.command('getprop ro.build.version.release');
 console.log('Android version:', result.output);
+```
 
-// Click UI element (simplified API)
-await shellx.click('Settings');
-
-// Or use full API
-await shellx.click({ text: 'Settings', clickType: 'single' });
+### 2. Using Environment Variables
 
-// Find elements
-const elements = await shellx.find({
-  text: 'Submit',
-  multiple: true,
-  maxResults: 10
-});
+Create a `.env` file:
 
-console.log(`Found ${elements.count} elements`);
+```env
+DEVICE_ID=your-device-id
 ```
 
-### With Connection Callbacks
+Then use it in your code:
 
 ```typescript
 import { ShellX } from 'shellx-ai';
+import dotenv from 'dotenv';
+
+dotenv.config();
+
+const shellx = new ShellX({
+  deviceId: process.env.DEVICE_ID
+});
 
+await shellx.ready();
+// Start automating...
+```
+
+### 3. With Connection Events
+
+```typescript
 const shellx = new ShellX({
   deviceId: 'your-device-id',
-  timeout: 5000,
-  reconnect: true,
-  reconnectMaxAttempts: 5,
   onOpen: () => console.log('✅ Connected'),
   onClose: () => console.log('❌ Disconnected'),
-  onError: (error) => console.error('⚠️ Error:', error),
-  onMessage: (message) => console.log('📨 Message:', message)
+  onError: (error) => console.error('⚠️ Error:', error)
 });
 
-// Wait for connection
 await shellx.ready();
+```
 
-// Ready to use!
-await shellx.command('pm list packages');
+---
+
+## API Reference
+
+### ShellX Class
+
+The main class for Android automation.
+
+#### Constructor
+
+```typescript
+new ShellX(options: ShellXOptions)
 ```
 
-## 🎯 API Reference
+**Options:**
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `deviceId` | `string` | Yes | - | Device ID (UUID or identifier) |
+| `timeout` | `number` | No | `5000` | Connection timeout in ms |
+| `reconnect` | `boolean` | No | `true` | Enable auto-reconnect |
+| `reconnectMaxAttempts` | `number` | No | `5` | Max reconnect attempts |
+| `logLevel` | `LogLevel` | No | `INFO` | Log level (0=NONE, 1=ERROR, 2=WARN, 3=INFO, 4=DEBUG) |
+| `onOpen` | `() => void` | No | - | Callback when connection opens |
+| `onClose` | `() => void` | No | - | Callback when connection closes |
+| `onError` | `(error?) => void` | No | - | Callback on error |
+| `onMessage` | `(msg) => void` | No | - | Callback on message |
+
+#### Methods
+
+##### Connection
+
+| Method | Description | Returns |
+|--------|-------------|---------|
+| `ready()` | Wait for connection to be ready | `Promise<void>` |
+| `getClient()` | Get underlying ConnectionClient | `ConnectionClient` |
+
+##### UI Actions
 
-### Core Classes
+| Method | Description | Example |
+|--------|-------------|---------|
+| `click(selector)` | Click element | `await shellx.click('Submit')` |
+| `input(data)` | Input text | `await shellx.input({ text: 'Hello' })` |
+| `swipe(data)` | Swipe gesture | `await shellx.swipe({ fromX: 500, fromY: 1000, toX: 500, toY: 500 })` |
+| `press(key)` | Press key | `await shellx.press('BACK')` |
+| `wait(selector)` | Wait for element | `await shellx.wait('Loading')` |
+| `find(selector)` | Find elements | `await shellx.find('Button', { multiple: true })` |
 
-#### `ShellX`
+##### Device Operations
 
-Main class providing high-level automation utilities.
+| Method | Description | Example |
+|--------|-------------|---------|
+| `command(cmd)` | Execute shell command | `await shellx.command('ls -la')` |
+| `getScreenInfo()` | Get screen info | `await shellx.getScreenInfo()` |
+| `takeScreenshot()` | Take screenshot | `await shellx.takeScreenshot({ format: 'png' })` |
+| `getAppInfo(pkg)` | Get app info | `await shellx.getAppInfo('com.example.app')` |
+| `getAppList()` | Get app list | `await shellx.getAppList()` |
+| `clipboard(data)` | Clipboard operations | `await shellx.clipboard({ text: 'Hello' })` |
 
-**Constructor:**
+##### Advanced
+
+| Method | Description | Example |
+|--------|-------------|---------|
+| `executeActions(actions)` | Execute multiple actions | `await shellx.executeActions([{ text: 'OK' }, { cmd: 'ls' }])` |
+| `sendRawMessage(msg)` | Send raw WebSocket message | `await shellx.sendRawMessage({ screenInfo: {} })` |
+
+---
+
+## Type Definitions
+
+### Click
+
+Click on an element by text, ID, or coordinates.
+
+**Simplified form (click by text):**
 ```typescript
-constructor(options: ShellXOptions)
+await shellx.click('Submit');
+await shellx.click('Submit', { clickType: 'long' });
 ```
 
-**ShellXOptions:**
+**Full form:**
 ```typescript
-interface ShellXOptions {
-  deviceId: string;                      // Required: Device ID
-  timeout?: number;                      // Connection timeout (default: 5000ms)
-  reconnect?: boolean;                   // Enable auto-reconnect (default: true)
-  reconnectMaxAttempts?: number;         // Max reconnect attempts (default: 5)
-  reconnectInterval?: number;            // Reconnect interval (default: 1000ms)
-  pingInterval?: number;                 // Ping interval (default: 2000ms)
-  onOpen?: () => void;                   // Connection opened callback
-  onClose?: () => void;                  // Connection closed callback
-  onError?: (error?: Event) => void;     // Error callback
-  onReconnectFailed?: () => void;        // Reconnect failed callback
-  onMessage?: (message: WsServer) => void; // Message callback
-}
+await shellx.click({
+  text: 'Submit',           // Click by text
+  elementId: 'btn123',      // Or by element ID
+  resourceId: 'submit_btn', // Or by resource ID
+  x: 500,                   // Or by coordinates
+  y: 1000,
+  clickType: 'single',      // 'single' | 'double' | 'long' | 'normal'
+  timeout: 5000
+});
 ```
 
-**Methods:**
+### Input
 
-| Method | Description | Return Type |
-|--------|-------------|-------------|
-| `ready()` | Wait for connection to be ready | `Promise<void>` |
-| `click(data)` | Click element by ID, coordinates, or selector | `Promise<ActionResult>` |
-| `input(data)` | Input text into element | `Promise<ActionResult>` |
-| `swipe(data)` | Perform swipe gesture | `Promise<ActionResult>` |
-| `pressKey(data)` | Press hardware key | `Promise<ActionResult>` |
-| `wait(data)` | Wait for element condition | `Promise<ActionResult>` |
-| `find(data)` | Find UI elements | `Promise<FindResult>` |
-| `clipboard(data)` | Clipboard operations (get/set/paste) | `Promise<ActionResult>` |
-| `takeScreenshot(data)` | Capture screenshot | `Promise<ActionResult>` |
-| `getScreenInfo()` | Get screen information | `Promise<ScreenInfoResponse>` |
-| `executeActions(actions)` | Execute multiple actions in sequence | `Promise<ActionResult[]>` |
-
-**Element Finder Methods:**
-
-| Method | Description | Return Type |
-|--------|-------------|-------------|
-| `findElementWithRetry(selector, maxRetries, retryDelay)` | Find single element with retry | `Promise<UIElement \| null>` |
-| `findElementsWithRetry(selector, maxRetries, retryDelay, options)` | Find multiple elements | `Promise<UIElement[]>` |
-| `waitForAnyElement(selectors, timeout)` | Wait for any element to appear | `Promise<{element, selectorIndex} \| null>` |
-| `scrollToFindElement(selector, maxScrolls, direction)` | Scroll to find element | `Promise<UIElement \| null>` |
-
-**Shell Command Methods:**
-
-| Method | Description | Return Type |
-|--------|-------------|-------------|
-| `executeShellCommand(command, options)` | Execute shell command with monitoring | `Promise<ShellCommandResult>` |
-| `executeSimpleShellCommand(command, options)` | Execute simple shell command | `Promise<ShellCommandResult>` |
-| `executeShellCommands(commands, options)` | Execute multiple commands | `Promise<ShellCommandResult[]>` |
-| `adbCommand(command, options)` | Execute ADB command | `Promise<ShellCommandResult>` |
-| `executeCode(code, context, timeout)` | Execute code in sandboxed environment | `Promise<any>` |
-
-**Device Info Methods:**
-
-| Method | Description | Return Type |
-|--------|-------------|-------------|
-| `getDeviceInfo()` | Get comprehensive device information | `Promise<ShellCommandResult[]>` |
-| `getDeviceModel()` | Get device model | `Promise<string \| undefined>` |
-| `getAndroidVersion()` | Get Android version | `Promise<string \| undefined>` |
-| `getScreenSize()` | Get screen size | `Promise<string \| undefined>` |
-| `getBatteryInfo()` | Get battery information | `Promise<BatteryInfo \| undefined>` |
-| `getDeviceInfoSummary()` | Get device information summary | `Promise<DeviceInfo>` |
-
-**Navigation Methods:**
-
-| Method | Description | Return Type |
-|--------|-------------|-------------|
-| `navigateByPath(textPath)` | Navigate using text path | `Promise<boolean>` |
-| `clickByText(text, exact)` | Click element by text | `Promise<boolean>` |
-| `inputText(selector, text, options)` | Input text into field | `Promise<boolean>` |
-
-### Type Definitions
-
-#### `Click`
-
-```typescript
-interface Click {
-  targetElementId?: string;
-  targetResourceId?: string;
-  targetText?: string;
-  targetClass?: string;
-  targetX?: number;
-  targetY?: number;
-  clickType?: 'single' | 'double' | 'long';
-  wait?: number;
-  retry?: number;
-}
+Input text into a field.
+
+```typescript
+await shellx.input({
+  elementId: 'field123',
+  text: 'Hello World',
+  clear: true,              // Clear field before input
+  hideKeyboard: true        // Hide keyboard after input
+});
 ```
 
-#### `Input`
+### Swipe
+
+Perform swipe gesture.
 
 ```typescript
-interface Input {
-  targetElementId?: string;
-  targetResourceId?: string;
-  targetText?: string;
-  targetClass?: string;
-  text: string;
-  clear?: boolean;
-  hideKeyboard?: boolean;
-  wait?: number;
-  retry?: number;
-}
+await shellx.swipe({
+  fromX: 500,
+  fromY: 1000,
+  toX: 500,
+  toY: 500,
+  duration: 800            // Duration in ms
+});
 ```
 
-#### `Swipe`
+### Press
 
+Press hardware key.
+
+**Simplified:**
 ```typescript
-interface Swipe {
-  fromX: number;
-  fromY: number;
-  toX: number;
-  toY: number;
-  duration?: number;
-  wait?: number;
-  retry?: number;
-}
+await shellx.press('BACK');
+await shellx.press('HOME');
+await shellx.press('MENU', { longPress: true });
 ```
 
-#### `Command`
+**Full:**
+```typescript
+await shellx.press({
+  key: 'BACK',
+  longPress: false
+});
+```
+
+### Wait
 
+Wait for an element condition.
+
+**Simplified:**
 ```typescript
-interface Command {
-  cmd: string;
-  timeout?: number;
-  wait?: number;
-  retry?: number;
-}
+await shellx.wait('Submit');
+await shellx.wait('Loading', { timeout: 10000 });
 ```
 
-#### `ActionResult`
+**Full:**
+```typescript
+await shellx.wait({
+  text: 'Submit',
+  condition: 'visible',      // 'visible' | 'gone' | 'enabled'
+  timeout: 5000
+});
+```
 
+### Find
+
+Find UI elements.
+
+**Simplified:**
 ```typescript
-interface ActionResult {
-  success: boolean;
-  data?: any;
-  error?: string;
-  duration: number;
-}
+const result = await shellx.find('Button');
+const all = await shellx.find('Button', { multiple: true, maxResults: 10 });
+```
+
+**Full:**
+```typescript
+const result = await shellx.find({
+  text: 'Submit',
+  multiple: false,
+  maxResults: 100,
+  pressClick: true          // Auto-click after find
+});
 ```
 
-## 📚 Examples
+### Command
 
-### Example 1: UI Automation Workflow
+Execute shell command.
 
+**Simplified:**
 ```typescript
-import { createShellXWithShellMonitoring } from 'shellx-ai';
+const result = await shellx.command('ls -la');
+const result = await shellx.command('ls -la', { timeout: 5000 });
+```
+
+**Full:**
+```typescript
+const result = await shellx.command({
+  cmd: 'ls -la',
+  timeout: 10000,
+  wait: 1000               // Wait after command
+});
+```
+
+### Screenshot
+
+Take screenshot.
+
+```typescript
+const screenshot = await shellx.takeScreenshot({
+  format: 'png',            // 'png' | 'jpeg'
+  quality: 100,             // 0-100 for JPEG
+  saveToFile: true
+});
+```
 
-async function automateApp() {
-  const shellx = await createShellXWithShellMonitoring({
-    deviceId: process.env.SHELLX_DEVICE_ID
+### Clipboard
+
+Clipboard operations.
+
+```typescript
+// Get clipboard
+const result = await shellx.clipboard({ get: true });
+
+// Set clipboard
+await shellx.clipboard({ text: 'Hello' });
+
+// Paste clipboard
+await shellx.clipboard({ paste: true });
+```
+
+### ExecuteActions (Batch)
+
+Execute multiple actions in sequence.
+
+```typescript
+const result = await shellx.executeActions([
+  { text: 'Settings' },                    // Click
+  { cmd: 'ls -la' },                       // Command
+  { fromX: 500, fromY: 1000, toX: 500, toY: 500 },  // Swipe
+  { key: 'BACK' }                          // Press
+]);
+
+console.log(`Success: ${result.successCount}/${result.results.length}`);
+```
+
+---
+
+## Complete Working Example
+
+Here's a complete example that you can run directly:
+
+```typescript
+// File: example.ts
+import { ShellX } from 'shellx-ai';
+
+async function main() {
+  // 1. Create ShellX instance
+  const shellx = new ShellX({
+    deviceId: process.env.DEVICE_ID || 'your-device-id',
+    onOpen: () => console.log('✅ Connected!')
   });
 
   try {
-    // Navigate to settings
-    await shellx.clickByText('Settings');
-    await shellx.wait({ targetText: 'Accounts', condition: 'visible', timeout: 5000 });
-
-    // Click on account item
-    await shellx.click({ targetText: 'Accounts' });
-
-    // Input text
-    await shellx.input({
-      targetResourceId: 'username_field',
-      text: 'user@example.com',
-      clear: true
-    });
-
-    // Take screenshot
-    await shellx.takeScreenshot({
-      format: 'png',
-      quality: 90,
-      saveToFile: true
-    });
-
-    console.log('Automation completed successfully!');
+    // 2. Wait for connection
+    await shellx.ready();
+    console.log('📱 Connected to device');
+
+    // 3. Get screen info
+    const screen = await shellx.getScreenInfo();
+    console.log(`Screen: ${screen.width}x${screen.height}`);
+
+    // 4. Click element
+    await shellx.click('Settings');
+    console.log('✅ Clicked Settings');
+
+    // 5. Press back
+    await shellx.press('BACK');
+    console.log('✅ Pressed BACK');
+
+    // 6. Execute command
+    const result = await shellx.command('getprop ro.build.version.release');
+    console.log(`Android: ${result.output.trim()}`);
+
+    // 7. Take screenshot
+    const screenshot = await shellx.takeScreenshot({ format: 'png' });
+    console.log(`Screenshot: ${screenshot.imagePath}`);
+
+    // 8. Batch operations
+    const batch = await shellx.executeActions([
+      { text: 'Settings' },
+      { cmd: 'wm size' }
+    ]);
+    console.log(`Batch: ${batch.successCount}/${batch.results.length} successful`);
+
+    console.log('🎉 All operations completed!');
   } catch (error) {
-    console.error('Automation failed:', error);
+    console.error('❌ Error:', error);
   }
 }
 
-automateApp();
+main();
 ```
 
-### Example 2: Batch Command Execution
+Compile and run:
 
-```typescript
-import { createShellX } from 'shellx-ai';
-import ConnectionTaskClient from 'shellx-ai';
+```bash
+# Install dependencies
+npm install shellx-ai dotenv
 
-async function executeDeviceCommands() {
-  const client = new ConnectionTaskClient('device-id');
-  await client.waitForInitialization();
-  const shellx = createShellX(client);
+# Create .env file
+echo "DEVICE_ID=your-device-id" > .env
 
-  // Execute multiple commands
-  const commands = [
-    { command: 'pm list packages', title: 'List packages' },
-    { command: 'dumpsys battery', title: 'Get battery info' },
-    { command: 'wm size', title: 'Get screen size' }
-  ];
+# Run with tsx
+npx tsx example.ts
+```
 
-  const results = await shellx.executeShellCommands(commands, {
-    continueOnError: true,
-    timeout: 10000
-  });
+---
 
-  results.forEach((result, index) => {
-    console.log(`\n${commands[index].title}:`);
-    console.log(`Success: ${result.success}`);
-    console.log(`Output: ${result.output}`);
-    if (result.error) {
-      console.error(`Error: ${result.error}`);
-    }
-  });
-}
+## Response Types
 
-executeDeviceCommands();
+All operations return a result object with the following structure:
+
+```typescript
+interface Result {
+  success: boolean;      // Operation success status
+  error?: string;        // Error message if failed
+  duration: number;      // Operation duration in ms
+  timestamp: number;     // Operation timestamp
+  // ... additional fields specific to each operation
+}
 ```
 
-### Example 3: Advanced Element Finding
+### CommandResult
 
 ```typescript
-async function findAndInteract() {
-  const shellx = await createShellXWithShellMonitoring({
-    deviceId: 'device-id'
-  });
-
-  // Find element with retry
-  const element = await shellx.findElementWithRetry(
-    { text: 'Submit Button', visible: true, clickable: true },
-    5,  // max retries
-    1000  // retry delay
-  );
-
-  if (element) {
-    console.log('Found element:', element.elementId);
-    shellx.printElementInfo(element);
-  } else {
-    console.log('Element not found');
-
-    // Try scrolling to find it
-    const foundElement = await shellx.scrollToFindElement(
-      { text: 'Submit Button' },
-      5,
-      'down'
-    );
-
-    if (foundElement) {
-      console.log('Found after scrolling!');
-      await shellx.click({ targetElementId: foundElement.elementId });
-    }
-  }
+{
+  success: boolean;
+  output: string;        // Command output
+  error?: string;
+  exitCode?: number;
+  duration: number;
+  cmd: string;
+  timestamp: number;
 }
+```
+
+### FindResult
 
-findAndInteract();
+```typescript
+{
+  success: boolean;
+  found: boolean;
+  count: number;         // Number of elements found
+  elements: Array<{
+    id: string;
+    text: string;
+    class: string;
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+    visible: boolean;
+    clickable: boolean;
+  }>;
+  duration: number;
+  timestamp: number;
+}
 ```
 
-### Example 4: Action Sequence
+### ScreenInfoResult
 
 ```typescript
-async function executeActionSequence() {
-  const shellx = await createShellXWithShellMonitoring({
-    deviceId: 'device-id'
-  });
+{
+  success: boolean;
+  width: number;
+  height: number;
+  density: number;
+  screenOn: boolean;
+  screenUnlocked: boolean;
+  foregroundApp?: string;
+  foregroundActivity?: string;
+  model?: string;
+  androidVersion?: string;
+  manufacturer?: string;
+  duration: number;
+  timestamp: number;
+}
+```
+
+---
 
-  // Execute multiple actions
-  const actions = [
-    // Click settings
-    { targetText: 'Settings' },
+## Logging
 
-    // Wait for menu
-    { targetText: 'Network', condition: 'visible', timeout: 5000 },
+Control logging level:
+
+```typescript
+const shellx = new ShellX({
+  deviceId: 'your-device-id',
+  logLevel: 3  // 0=NONE, 1=ERROR, 2=WARN, 3=INFO, 4=DEBUG
+});
 
-    // Click network
-    { targetText: 'Network' },
+// Or at runtime
+shellx.setLogLevel(4);         // Enable debug logging
+shellx.enableDebugLogging();   // Shortcut
+shellx.disableLogging();       // Disable all logging
+```
 
-    // Execute command
-    { cmd: 'dumpsys wifi' },
+---
 
-    // Take screenshot
-    { format: 'png' }
-  ];
+## Error Handling
 
-  const results = await shellx.executeActions(actions);
+```typescript
+try {
+  await shellx.click('Settings');
+} catch (error) {
+  if (error instanceof Error) {
+    console.error('Click failed:', error.message);
+  }
+}
 
-  results.forEach((result, index) => {
-    const status = result.success ? '✅' : '❌';
-    console.log(`Action ${index + 1}: ${status}`);
-    if (!result.success) {
-      console.error(`  Error: ${result.error}`);
-    }
-  });
+// Or check result
+const result = await shellx.click('Settings');
+if (!result.success) {
+  console.error('Failed:', result.error);
 }
+```
+
+---
 
-executeActionSequence();
+## Advanced Usage
+
+### Wait for Multiple Elements
+
+```typescript
+const result = await shellx.waitAnyElement([
+  { text: 'OK' },
+  { text: 'Confirm' },
+  { text: 'Submit' }
+], 10000);
 ```
 
-## 🛠️ Development
+### Scroll to Find Element
 
-### Setup
+```typescript
+const element = await shellx.scrollToFindElement(
+  { text: 'Target Item' },
+  5,      // max scroll attempts
+  'down'  // direction
+);
+```
 
-```bash
-# Clone repository
-git clone https://github.com/10cl/shellx.git
-cd shellx
+### Find with Retry
 
-# Install dependencies
-npm install
-
-# Build project
-npm run build
-
-# Run tests
-npm test
-```
-
-### Available Scripts
-
-| Script | Description |
-|--------|-------------|
-| `npm run build` | Compile TypeScript to JavaScript |
-| `npm run build:watch` | Watch mode for compilation |
-| `npm run type-check` | Type check without emitting files |
-| `npm run lint` | Run ESLint |
-| `npm run lint:fix` | Fix ESLint errors automatically |
-| `npm run format` | Format code with Prettier |
-| `npm run format:check` | Check code formatting |
-| `npm test` | Run tests |
-| `npm run test:coverage` | Run tests with coverage |
-| `npm run clean` | Remove dist directory |
-
-### Project Structure
-
-```
-shellx-ai/
-├── src/
-│   ├── automation/
-│   │   ├── element-finder.ts       # Element finding with retry logic
-│   │   ├── ui-action-handler.ts    # UI action execution
-│   │   └── device-info-helper.ts   # Device information retrieval
-│   ├── shell/
-│   │   ├── output-buffer.ts         # Shell output buffering
-│   │   └── shell-command-executor.ts # Shell command execution
-│   ├── utils/
-│   │   └── retry-helper.ts          # Generic retry mechanism
-│   ├── index.ts                     # Main connection client
-│   ├── shellx.ts                    # Main ShellX class
-│   ├── protocol.ts                  # Protocol type definitions
-│   ├── types.ts                     # Simplified type definitions
-│   ├── domain-manager.ts            # Domain management
-│   └── utils.ts                     # Utility functions
-├── dist/                            # Compiled output
-├── package.json
-├── tsconfig.json
-├── jest.config.js
-├── .eslintrc.json
-├── .prettierrc.json
-└── README.md
-```
-
-## 🧪 Testing
+```typescript
+const element = await shellx.findElementWithRetry(
+  { text: 'Submit', visible: true },
+  3,      // max retries
+  1000    // retry delay
+);
+```
+
+---
+
+## Platform Support
+
+### Node.js
 
 ```bash
-# Run all tests
-npm test
+npm install shellx-ai ws
+```
 
-# Run tests in watch mode
-npm run test:watch
+```typescript
+import { ShellX } from 'shellx-ai';
+const shellx = new ShellX({ deviceId: 'device-id' });
+```
 
-# Generate coverage report
-npm run test:coverage
+### Browser
 
-# Type checking
-npm run type-check
+```bash
+npm install shellx-ai
+```
 
-# Linting
-npm run lint
+```typescript
+import { ShellX } from 'shellx-ai';
+const shellx = new ShellX({ deviceId: 'device-id' });
 ```
 
-## 🤝 Contributing
+---
 
-We welcome contributions! Please follow these steps:
+## Troubleshooting
 
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
+### Connection Issues
+
+```typescript
+const shellx = new ShellX({
+  deviceId: 'your-device-id',
+  timeout: 10000,           // Increase timeout
+  reconnect: true,          // Enable auto-reconnect
+  reconnectMaxAttempts: 10, // More attempts
+  onError: (error) => console.error('Connection error:', error)
+});
+```
 
-### Code Style
+### Element Not Found
 
-- Use TypeScript for all new features
-- Follow ESLint rules (`npm run lint`)
-- Format code with Prettier (`npm run format`)
-- Add JSDoc comments for public APIs
-- Write tests for new functionality
-- Ensure all tests pass before submitting
+```typescript
+// Wait for element first
+await shellx.wait('Submit', { timeout: 10000 });
 
-## 📝 License
+// Then click
+await shellx.click('Submit');
+```
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+### Command Timeout
 
-## 🆘 Support
+```typescript
+const result = await shellx.command({
+  cmd: 'long-running-command',
+  timeout: 30000  // 30 seconds
+});
+```
 
-- 📚 [Documentation](https://github.com/10cl/shellx/wiki)
-- 🐛 [Issue Tracker](https://github.com/10cl/shellx/issues)
-- 💬 [Discussions](https://github.com/10cl/shellx/discussions)
+---
 
-## 🌟 Acknowledgments
+## See Also
 
-- Built with [TypeScript](https://www.typescriptlang.org/)
-- Powered by [WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket)
-- Tested with [Jest](https://jestjs.io/)
+- [API-GUIDE.md](./API-GUIDE.md) - Detailed API guide
+- [API-QUICK-REFERENCE.md](./API-QUICK-REFERENCE.md) - Quick reference
+- [example/](./example/) - Complete working examples
 
 ---
 
-<div align="center">
+## License
+
+MIT License - see [LICENSE](LICENSE) file.
 
-  **Built with ❤️ for the automation community**
+---
 
-  [⬆ Back to Top](#shellx-ai)
+## Support
 
-</div>
+- 📚 [Documentation](https://github.com/10cl/shellx)
+- 🐛 [Issues](https://github.com/10cl/shellx/issues)
+- 💬 [Discussions](https://github.com/10cl/shellx/discussions)