@aiscene/android 1.3.5 → 1.6.0-cache

package/dist/lib/mcp-server.js

@@ -24,24 +24,26 @@ var __webpack_modules__ = {
             return obj;
         }
         const debugScrcpy = (0, _midscene_shared_logger__rspack_import_3.getDebug)('android:scrcpy');
+        const warnScrcpy = (0, _midscene_shared_logger__rspack_import_3.getDebug)('android:scrcpy', {
+            console: true
+        });
         const NAL_TYPE_IDR = 5;
         const NAL_TYPE_SPS = 7;
         const NAL_TYPE_PPS = 8;
         const NAL_TYPE_MASK = 0x1f;
-        const START_CODE_4_BYTE = Buffer.from([
-            0x00,
-            0x00,
-            0x00,
-            0x01
-        ]);
         const DEFAULT_MAX_SIZE = 0;
-        const DEFAULT_VIDEO_BIT_RATE = 2000000;
+        const DEFAULT_VIDEO_BIT_RATE = 100000000;
+        const MAX_VIDEO_BIT_RATE = 100000000;
         const DEFAULT_IDLE_TIMEOUT_MS = 30000;
         const MAX_KEYFRAME_WAIT_MS = 5000;
         const FRESH_FRAME_TIMEOUT_MS = 300;
         const KEYFRAME_POLL_INTERVAL_MS = 200;
         const MAX_SCAN_BYTES = 1000;
         const CONNECTION_WAIT_MS = 1000;
+        const BUSY_LOOP_WINDOW_MS = 1000;
+        const BUSY_LOOP_MAX_READS = 500;
+        const BUSY_LOOP_COOLDOWN_MS = 50;
+        const BUSY_LOOP_WARN_INTERVAL_MS = 5000;
         const DEFAULT_SCRCPY_CONFIG = {
             enabled: false,
             maxSize: DEFAULT_MAX_SIZE,
@@ -81,21 +83,21 @@ var __webpack_modules__ = {
                 try {
                     this.isConnecting = true;
                     debugScrcpy('Starting scrcpy connection...');
-                    const { AdbScrcpyClient, AdbScrcpyOptions2_1 } = await import("@yume-chan/adb-scrcpy");
+                    const { AdbScrcpyClient, AdbScrcpyOptions3_3_3 } = await import("@yume-chan/adb-scrcpy");
                     const { ReadableStream } = await import("@yume-chan/stream-extra");
-                    const { ScrcpyOptions3_1, DefaultServerPath, h264SearchConfiguration } = await import("@yume-chan/scrcpy");
-                    this.h264SearchConfigFn = h264SearchConfiguration;
+                    const { DefaultServerPath } = await import("@yume-chan/scrcpy");
                     const serverBinPath = this.resolveServerBinPath();
                     await AdbScrcpyClient.pushServer(this.adb, ReadableStream.from((0, node_fs__rspack_import_0.createReadStream)(serverBinPath)));
-                    const scrcpyOptions = new ScrcpyOptions3_1({
+                    const scrcpyOptions = new AdbScrcpyOptions3_3_3({
                         audio: false,
                         control: false,
                         maxSize: this.options.maxSize,
                         videoBitRate: this.options.videoBitRate,
-                        sendFrameMeta: false,
-                        videoCodecOptions: 'i-frame-interval=0'
+                        maxFps: 10,
+                        sendFrameMeta: true,
+                        videoCodecOptions: 'i-frame-interval=0,bitrate-mode=2'
                     });
-                    this.scrcpyClient = await AdbScrcpyClient.start(this.adb, DefaultServerPath, new AdbScrcpyOptions2_1(scrcpyOptions));
+                    this.scrcpyClient = await AdbScrcpyClient.start(this.adb, DefaultServerPath, scrcpyOptions);
                     const videoStreamPromise = this.scrcpyClient.videoStream;
                     if (!videoStreamPromise) throw new Error('Scrcpy client did not provide video stream');
                     this.videoStream = await videoStreamPromise;
@@ -118,12 +120,13 @@ var __webpack_modules__ = {
                 }
             }
             resolveServerBinPath() {
-                const androidPkgJson = (0, node_module__rspack_import_1.createRequire)(__rslib_import_meta_url__).resolve('@midscene/android/package.json');
+                const androidPkgJson = (0, node_module__rspack_import_1.createRequire)(__rslib_import_meta_url__).resolve('@aiscene/android/package.json');
                 return node_path__rspack_import_2_default().join(node_path__rspack_import_2_default().dirname(androidPkgJson), 'bin', 'scrcpy-server');
             }
             getFfmpegPath() {
                 try {
-                    const ffmpegInstaller = __webpack_require__("@ffmpeg-installer/ffmpeg");
+                    const dynamicRequire = (0, node_module__rspack_import_1.createRequire)(__rslib_import_meta_url__);
+                    const ffmpegInstaller = dynamicRequire('@ffmpeg-installer/ffmpeg');
                     debugScrcpy(`Using ffmpeg from npm package: ${ffmpegInstaller.path}`);
                     return ffmpegInstaller.path;
                 } catch (error) {
@@ -138,22 +141,47 @@ var __webpack_modules__ = {
                 this.consumeFramesLoop(reader);
             }
             async consumeFramesLoop(reader) {
+                let readCount = 0;
+                let windowStart = Date.now();
+                let lastBusyWarn = 0;
+                let totalReads = 0;
                 try {
                     while(true){
                         const { done, value } = await reader.read();
                         if (done) break;
+                        totalReads++;
+                        readCount++;
+                        const now = Date.now();
+                        const elapsed = now - windowStart;
+                        if (elapsed >= BUSY_LOOP_WINDOW_MS) {
+                            const readsPerSec = readCount / elapsed * 1000;
+                            if (readCount > BUSY_LOOP_MAX_READS) {
+                                if (now - lastBusyWarn >= BUSY_LOOP_WARN_INTERVAL_MS) {
+                                    warnScrcpy(`[CPU-DIAG] Possible busy loop detected! ${readCount} reads in ${elapsed}ms (${readsPerSec.toFixed(0)} reads/sec). Total reads: ${totalReads}. Throttling with ${BUSY_LOOP_COOLDOWN_MS}ms delay.`);
+                                    lastBusyWarn = now;
+                                }
+                                await new Promise((resolve)=>setTimeout(resolve, BUSY_LOOP_COOLDOWN_MS));
+                            } else debugScrcpy(`[CPU-DIAG] Frame loop stats: ${readCount} reads in ${elapsed}ms (${readsPerSec.toFixed(1)} reads/sec), total: ${totalReads}`);
+                            readCount = 0;
+                            windowStart = Date.now();
+                        }
                         this.processFrame(value);
                     }
                 } catch (error) {
-                    debugScrcpy(`Frame consumer error: ${error}`);
+                    debugScrcpy(`Frame consumer error (total reads: ${totalReads}): ${error}`);
                     await this.disconnect();
                 }
+                debugScrcpy(`Frame consumer loop ended normally (total reads: ${totalReads})`);
             }
             processFrame(packet) {
+                if ('configuration' === packet.type) {
+                    this.spsHeader = Buffer.from(packet.data);
+                    debugScrcpy(`Received SPS/PPS configuration: ${this.spsHeader.length}B`);
+                    return;
+                }
                 const frameBuffer = Buffer.from(packet.data);
-                const actualKeyFrame = detectH264KeyFrame(frameBuffer);
-                if (actualKeyFrame && !this.spsHeader) this.extractSpsHeader(frameBuffer);
-                if (actualKeyFrame && this.spsHeader) {
+                const isKeyFrame = detectH264KeyFrame(frameBuffer);
+                if (isKeyFrame && this.spsHeader) {
                     this.lastRawKeyframe = frameBuffer;
                     if (this.keyframeResolvers.length > 0) {
                         const combined = Buffer.concat([
@@ -164,23 +192,7 @@ var __webpack_modules__ = {
                     }
                 }
             }
-            extractSpsHeader(frameBuffer) {
-                if (!this.h264SearchConfigFn) return;
-                try {
-                    const config = this.h264SearchConfigFn(new Uint8Array(frameBuffer));
-                    if (!config.sequenceParameterSet || !config.pictureParameterSet) return;
-                    this.spsHeader = Buffer.concat([
-                        START_CODE_4_BYTE,
-                        Buffer.from(config.sequenceParameterSet),
-                        START_CODE_4_BYTE,
-                        Buffer.from(config.pictureParameterSet)
-                    ]);
-                    debugScrcpy(`Extracted SPS/PPS: SPS=${config.sequenceParameterSet.length}B, PPS=${config.pictureParameterSet.length}B, total=${this.spsHeader.length}B`);
-                } catch (error) {
-                    debugScrcpy(`Failed to extract SPS/PPS from keyframe: ${error}`);
-                }
-            }
-            async getScreenshotPng() {
+            async getScreenshotJpeg() {
                 const perfStart = Date.now();
                 const t1 = Date.now();
                 await this.ensureConnected();
@@ -210,7 +222,7 @@ var __webpack_modules__ = {
                 this.resetIdleTimer();
                 debugScrcpy(`Decoding H.264 stream: ${keyframeBuffer.length} bytes (${frameSource})`);
                 const t4 = Date.now();
-                const result = await this.decodeH264ToPng(keyframeBuffer);
+                const result = await this.decodeH264ToJpeg(keyframeBuffer);
                 const decodeTime = Date.now() - t4;
                 const totalTime = Date.now() - perfStart;
                 debugScrcpy(`Performance: total=${totalTime}ms (connect=${connectTime}ms, spsWait=${spsWaitTime}ms, frameWait=${frameWaitTime}ms[${frameSource}], decode=${decodeTime}ms)`);
@@ -273,7 +285,7 @@ var __webpack_modules__ = {
                     return false;
                 }
             }
-            async decodeH264ToPng(h264Buffer) {
+            async decodeH264ToJpeg(h264Buffer) {
                 const { spawn } = await import("node:child_process");
                 return new Promise((resolve, reject)=>{
                     const ffmpegArgs = [
@@ -286,7 +298,9 @@ var __webpack_modules__ = {
                         '-f',
                         'image2pipe',
                         '-vcodec',
-                        'png',
+                        'mjpeg',
+                        '-q:v',
+                        '5',
                         '-loglevel',
                         'error',
                         'pipe:1'
@@ -309,13 +323,13 @@ var __webpack_modules__ = {
                     });
                     ffmpeg.on('close', (code)=>{
                         if (0 === code && chunks.length > 0) {
-                            const pngBuffer = Buffer.concat(chunks);
-                            debugScrcpy(`FFmpeg decode successful, PNG size: ${pngBuffer.length} bytes`);
-                            resolve(pngBuffer);
+                            const jpegBuffer = Buffer.concat(chunks);
+                            debugScrcpy(`FFmpeg decode successful, JPEG size: ${jpegBuffer.length} bytes`);
+                            resolve(jpegBuffer);
                         } else {
                             const errorMsg = stderrOutput || `FFmpeg exited with code ${code}`;
                             debugScrcpy(`FFmpeg decode failed: ${errorMsg}`);
-                            reject(new Error(`H.264 to PNG decode failed: ${errorMsg}`));
+                            reject(new Error(`H.264 to JPEG decode failed: ${errorMsg}`));
                         }
                     });
                     ffmpeg.on('error', (error)=>{
@@ -347,7 +361,6 @@ var __webpack_modules__ = {
                 this.spsHeader = null;
                 this.lastRawKeyframe = null;
                 this.isInitialized = false;
-                this.h264SearchConfigFn = null;
                 this.keyframeResolvers = [];
                 if (reader) try {
                     reader.cancel();
@@ -375,20 +388,19 @@ var __webpack_modules__ = {
                 _define_property(this, "keyframeResolvers", []);
                 _define_property(this, "lastRawKeyframe", null);
                 _define_property(this, "videoResolution", null);
-                _define_property(this, "h264SearchConfigFn", null);
                 _define_property(this, "streamReader", null);
                 this.adb = adb;
+                const requestedBitRate = options.videoBitRate ?? DEFAULT_VIDEO_BIT_RATE;
+                const clampedBitRate = Math.min(requestedBitRate, MAX_VIDEO_BIT_RATE);
+                if (requestedBitRate > MAX_VIDEO_BIT_RATE) warnScrcpy(`videoBitRate ${requestedBitRate} exceeds maximum ${MAX_VIDEO_BIT_RATE}, clamped to ${clampedBitRate}`);
                 this.options = {
                     maxSize: options.maxSize ?? DEFAULT_MAX_SIZE,
-                    videoBitRate: options.videoBitRate ?? DEFAULT_VIDEO_BIT_RATE,
+                    videoBitRate: clampedBitRate,
                     idleTimeoutMs: options.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS
                 };
             }
         }
     },
-    "@ffmpeg-installer/ffmpeg" (module) {
-        module.exports = require("@ffmpeg-installer/ffmpeg");
-    },
     "@midscene/shared/logger" (module) {
         module.exports = require("@midscene/shared/logger");
     },
@@ -592,18 +604,13 @@ var __webpack_exports__ = {};
         resolveConfig(deviceInfo) {
             if (this.resolvedConfig) return this.resolvedConfig;
             const config = this.scrcpyConfig;
-            let maxSize = config?.maxSize ?? scrcpy_manager.o.maxSize;
-            if (config?.maxSize === void 0) {
-                const physicalMax = Math.max(deviceInfo.physicalWidth, deviceInfo.physicalHeight);
-                const scale = this.screenshotResizeScale ?? 1 / deviceInfo.dpr;
-                maxSize = Math.round(physicalMax * scale);
-                debugAdapter(`Auto-calculated maxSize: ${maxSize} (physical=${physicalMax}, scale=${scale.toFixed(3)}, ${void 0 !== this.screenshotResizeScale ? 'from screenshotResizeScale' : 'from 1/dpr'})`);
-            }
+            const maxSize = config?.maxSize ?? scrcpy_manager.o.maxSize;
+            const videoBitRate = config?.videoBitRate ?? scrcpy_manager.o.videoBitRate;
             this.resolvedConfig = {
                 enabled: this.isEnabled(),
                 maxSize,
                 idleTimeoutMs: config?.idleTimeoutMs ?? scrcpy_manager.o.idleTimeoutMs,
-                videoBitRate: config?.videoBitRate ?? scrcpy_manager.o.videoBitRate
+                videoBitRate
             };
             return this.resolvedConfig;
         }
@@ -638,8 +645,8 @@ var __webpack_exports__ = {};
         }
         async screenshotBase64(deviceInfo) {
             const manager = await this.ensureManager(deviceInfo);
-            const screenshotBuffer = await manager.getScreenshotPng();
-            return (0, img_namespaceObject.createImgBase64ByFormat)('png', screenshotBuffer.toString('base64'));
+            const screenshotBuffer = await manager.getScreenshotJpeg();
+            return (0, img_namespaceObject.createImgBase64ByFormat)('jpeg', screenshotBuffer.toString('base64'));
         }
         getResolution() {
             return this.manager?.getResolution() ?? null;
@@ -650,8 +657,7 @@ var __webpack_exports__ = {};
             debugAdapter(`Using scrcpy resolution: ${resolution.width}x${resolution.height}`);
             return {
                 width: resolution.width,
-                height: resolution.height,
-                dpr: deviceInfo.dpr
+                height: resolution.height
             };
         }
         getScalingRatio(physicalWidth) {
@@ -670,16 +676,14 @@ var __webpack_exports__ = {};
             }
             this.resolvedConfig = null;
         }
-        constructor(deviceId, scrcpyConfig, screenshotResizeScale){
+        constructor(deviceId, scrcpyConfig){
             _define_property(this, "deviceId", void 0);
             _define_property(this, "scrcpyConfig", void 0);
-            _define_property(this, "screenshotResizeScale", void 0);
             _define_property(this, "manager", void 0);
             _define_property(this, "resolvedConfig", void 0);
             _define_property(this, "initFailed", void 0);
             this.deviceId = deviceId;
             this.scrcpyConfig = scrcpyConfig;
-            this.screenshotResizeScale = screenshotResizeScale;
             this.manager = null;
             this.resolvedConfig = null;
             this.initFailed = false;
@@ -906,7 +910,7 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
             });
         }
         getScrcpyAdapter() {
-            if (!this.scrcpyAdapter) this.scrcpyAdapter = new ScrcpyDeviceAdapter(this.deviceId, this.options?.scrcpyConfig, this.options?.screenshotResizeScale);
+            if (!this.scrcpyAdapter) this.scrcpyAdapter = new ScrcpyDeviceAdapter(this.deviceId, this.options?.scrcpyConfig);
             return this.scrcpyAdapter;
         }
         async getDevicePhysicalInfo() {
@@ -1152,8 +1156,7 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
             const logicalHeight = Math.round(height * scale);
             return {
                 width: logicalWidth,
-                height: logicalHeight,
-                dpr: this.devicePixelRatio
+                height: logicalHeight
             };
         }
         async cacheFeatureForPoint(center, options) {
@@ -1439,7 +1442,7 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         async ensureYadb() {
             if (!this.yadbPushed) {
                 const adb = await this.getAdb();
-                const androidPkgJson = (0, external_node_module_.createRequire)(__rslib_import_meta_url__).resolve('@midscene/android/package.json');
+                const androidPkgJson = (0, external_node_module_.createRequire)(__rslib_import_meta_url__).resolve('@aiscene/android/package.json');
                 const yadbBin = external_node_path_default().join(external_node_path_default().dirname(androidPkgJson), 'bin', 'yadb');
                 await adb.push(yadbBin, '/data/local/tmp');
                 this.yadbPushed = true;
@@ -1896,7 +1899,7 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         constructor(toolsManager){
             super({
                 name: '@midscene/android-mcp',
-                version: __VERSION__,
+                version: "1.6.0-cache",
                 description: 'Control the Android device using natural language commands'
             }, toolsManager);
         }

package/dist/types/cli.d.ts

@@ -0,0 +1 @@
+export { }

package/dist/types/index.d.ts

@@ -2,10 +2,12 @@ import { AbstractInterface } from '@midscene/core/device';
 import type { ActionParam } from '@midscene/core';
 import type { ActionReturn } from '@midscene/core';
 import { ADB } from 'appium-adb';
+import type { Adb } from '@yume-chan/adb';
 import { Agent } from '@midscene/core/agent';
 import { AgentOpt } from '@midscene/core/agent';
 import { AndroidDeviceInputOpt } from '@midscene/core/device';
 import { AndroidDeviceOpt } from '@midscene/core/device';
+import { BaseMidsceneTools } from '@midscene/shared/mcp';
 import { Device } from 'appium-adb';
 import { DeviceAction } from '@midscene/core';
 import { ElementCacheFeature } from '@midscene/core';
@@ -16,6 +18,7 @@ import { overrideAIConfig } from '@midscene/shared/env';
 import { Point } from '@midscene/core';
 import { Rect } from '@midscene/core';
 import { Size } from '@midscene/core';
+import { ToolDefinition } from '@midscene/shared/mcp';
 
 declare type ActionArgs<T extends DeviceAction> = [ActionParam<T>] extends [undefined] ? [] : [ActionParam<T>];
 
@@ -207,16 +210,217 @@ export declare class AndroidDevice implements AbstractInterface {
     hideKeyboard(options?: AndroidDeviceInputOpt, timeoutMs?: number): Promise<boolean>;
 }
 
+/**
+ * Android-specific tools manager
+ * Extends BaseMidsceneTools to provide Android ADB device connection tools
+ */
+export declare class AndroidMidsceneTools extends BaseMidsceneTools<AndroidAgent> {
+    protected createTemporaryDevice(): AndroidDevice;
+    protected ensureAgent(deviceId?: string): Promise<AndroidAgent>;
+    /**
+     * Provide Android-specific platform tools
+     */
+    protected preparePlatformTools(): ToolDefinition[];
+}
+
 declare type DeviceActionAndroidBackButton = DeviceAction<undefined, void>;
 
 declare type DeviceActionAndroidHomeButton = DeviceAction<undefined, void>;
 
 declare type DeviceActionAndroidRecentAppsButton = DeviceAction<undefined, void>;
 
+declare interface DevicePhysicalInfo {
+    physicalWidth: number;
+    physicalHeight: number;
+    dpr: number;
+    orientation: number;
+    isCurrentOrientation?: boolean;
+}
+
 export declare function getConnectedDevices(): Promise<Device[]>;
 
 export { overrideAIConfig }
 
+declare interface ResolvedScrcpyConfig {
+    enabled: boolean;
+    maxSize: number;
+    videoBitRate: number;
+    idleTimeoutMs: number;
+}
+
+declare interface ScrcpyConfig {
+    enabled?: boolean;
+    maxSize?: number;
+    videoBitRate?: number;
+    idleTimeoutMs?: number;
+}
+
+/**
+ * Adapter that encapsulates all scrcpy-related logic for AndroidDevice.
+ * Handles config normalization, manager lifecycle, screenshot, and resolution.
+ */
+export declare class ScrcpyDeviceAdapter {
+    private deviceId;
+    private scrcpyConfig;
+    private manager;
+    private resolvedConfig;
+    private initFailed;
+    constructor(deviceId: string, scrcpyConfig: ScrcpyConfig | undefined);
+    isEnabled(): boolean;
+    /**
+     * Initialize scrcpy connection. Called once during device.connect().
+     * If initialization fails, marks scrcpy as permanently disabled (no further retries).
+     */
+    initialize(deviceInfo: DevicePhysicalInfo): Promise<void>;
+    /**
+     * Resolve scrcpy config.
+     * maxSize defaults to 0 (no scaling, full physical resolution) so the Agent layer
+     * receives the highest quality image for AI processing.
+     * videoBitRate is auto-scaled based on physical pixel count to ensure
+     * sufficient quality for all-I-frame H.264 encoding.
+     */
+    resolveConfig(deviceInfo: DevicePhysicalInfo): ResolvedScrcpyConfig;
+    /**
+     * Get or create the ScrcpyScreenshotManager.
+     * Uses dynamic import for @yume-chan packages (ESM-only, must use await import in CJS builds).
+     */
+    ensureManager(deviceInfo: DevicePhysicalInfo): Promise<ScrcpyScreenshotManager>;
+    /**
+     * Take a screenshot via scrcpy, returns base64 string.
+     * Throws on failure (caller should fallback to ADB).
+     */
+    screenshotBase64(deviceInfo: DevicePhysicalInfo): Promise<string>;
+    /**
+     * Get scrcpy's actual video resolution.
+     * Returns null if scrcpy is not connected yet.
+     */
+    getResolution(): {
+        width: number;
+        height: number;
+    } | null;
+    /**
+     * Compute size from scrcpy resolution.
+     * Returns null if scrcpy is not connected.
+     */
+    getSize(deviceInfo: DevicePhysicalInfo): Size | null;
+    /**
+     * Calculate the scaling ratio from physical to scrcpy resolution.
+     */
+    getScalingRatio(physicalWidth: number): number | null;
+    disconnect(): Promise<void>;
+}
+
+declare class ScrcpyScreenshotManager {
+    private adb;
+    private scrcpyClient;
+    private videoStream;
+    private spsHeader;
+    private idleTimer;
+    private isConnecting;
+    private isInitialized;
+    private options;
+    private ffmpegAvailable;
+    private keyframeResolvers;
+    private lastRawKeyframe;
+    private videoResolution;
+    private streamReader;
+    constructor(adb: Adb, options?: ScrcpyScreenshotOptions);
+    /**
+     * Validate environment prerequisites (ffmpeg, scrcpy-server, etc.)
+     * Must be called once after construction, before any screenshot operations.
+     * Throws if prerequisites are not met.
+     */
+    validateEnvironment(): Promise<void>;
+    /**
+     * Ensure scrcpy connection is active
+     */
+    ensureConnected(): Promise<void>;
+    /**
+     * Resolve path to scrcpy server binary
+     */
+    private resolveServerBinPath;
+    /**
+     * Get ffmpeg executable path
+     * Priority: @ffmpeg-installer/ffmpeg > system ffmpeg
+     */
+    private getFfmpegPath;
+    /**
+     * Consume video frames and keep latest frame
+     */
+    private startFrameConsumer;
+    /**
+     * Main frame consumption loop
+     * Includes busy-loop detection: if reader.read() resolves too fast
+     * (e.g. broken stream returning immediately), we throttle to prevent 100% CPU.
+     */
+    private consumeFramesLoop;
+    /**
+     * Process a single video packet from the scrcpy stream.
+     * With sendFrameMeta: true, the stream emits properly framed packets:
+     * - "configuration" packets contain SPS/PPS header data
+     * - "data" packets contain complete video frames with correct boundaries
+     * This avoids the frame-splitting issue that occurs with sendFrameMeta: false
+     * at high resolutions where raw chunks may not align with frame boundaries.
+     */
+    private processFrame;
+    /**
+     * Get screenshot as JPEG.
+     * Tries to get a fresh frame within a short timeout. If the screen is static
+     * (no new frames arrive), falls back to the latest cached keyframe.
+     */
+    getScreenshotJpeg(): Promise<Buffer>;
+    /**
+     * Get the actual video stream resolution
+     * Returns null if scrcpy is not connected yet
+     */
+    getResolution(): {
+        width: number;
+        height: number;
+    } | null;
+    /**
+     * Notify all pending keyframe waiters
+     */
+    private notifyKeyframeWaiters;
+    /**
+     * Wait for the next keyframe to arrive
+     */
+    private waitForNextKeyframe;
+    /**
+     * Ensure ffmpeg is available for PNG conversion
+     */
+    private ensureFfmpegAvailable;
+    /**
+     * Wait for first keyframe with SPS/PPS header
+     */
+    private waitForKeyframe;
+    /**
+     * Check if ffmpeg is available in the system
+     */
+    private checkFfmpegAvailable;
+    /**
+     * Decode H.264 data to JPEG using ffmpeg
+     */
+    private decodeH264ToJpeg;
+    /**
+     * Reset idle timeout timer
+     */
+    private resetIdleTimer;
+    /**
+     * Disconnect scrcpy
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Check if scrcpy is initialized and connected
+     */
+    isConnected(): boolean;
+}
+
+declare interface ScrcpyScreenshotOptions {
+    maxSize?: number;
+    videoBitRate?: number;
+    idleTimeoutMs?: number;
+}
+
 /**
  * Helper type to convert DeviceAction to wrapped method signature
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiscene/android",
-  "version": "1.3.5",
+  "version": "1.6.0-cache",
   "description": "Android automation library for Midscene",
   "keywords": [
     "Android UI automation",
@@ -12,6 +12,9 @@
   "main": "./dist/lib/index.js",
   "module": "./dist/es/index.mjs",
   "types": "./dist/types/index.d.ts",
+  "bin": {
+    "midscene-android": "./bin/midscene-android"
+  },
   "files": ["bin", "dist", "README.md"],
   "exports": {
     ".": {
@@ -39,13 +42,13 @@
     "test:ai:cache": "MIDSCENE_CACHE=true AI_TEST_TYPE=android npm run test"
   },
   "dependencies": {
-    "@midscene/core": "^1.3.4",
-    "@midscene/shared": "^1.3.4",
-    "@yume-chan/adb": "^1.1.0",
-    "@yume-chan/adb-scrcpy": "^1.1.0",
-    "@yume-chan/adb-server-node-tcp": "^1.1.0",
-    "@yume-chan/scrcpy": "^1.1.0",
-    "@yume-chan/stream-extra": "^1.0.0",
+    "@midscene/core": "workspace:*",
+    "@midscene/shared": "workspace:*",
+    "@yume-chan/adb": "2.5.1",
+    "@yume-chan/adb-scrcpy": "2.3.2",
+    "@yume-chan/adb-server-node-tcp": "2.5.2",
+    "@yume-chan/scrcpy": "2.3.0",
+    "@yume-chan/stream-extra": "2.1.0",
     "appium-adb": "12.12.1",
     "sharp": "^0.34.3"
   },
@@ -63,9 +66,5 @@
     "vitest": "3.0.5",
     "zod": "3.24.3"
   },
-  "license": "MIT",
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org"
-  }
+  "license": "MIT"
 }