@midscene/android-playground 1.7.3 → 1.7.4

package/dist/es/bin.mjs

@@ -1,7 +1,7 @@
 import node_path from "node:path";
 import { createScrcpyPreviewDescriptor, definePlaygroundPlatform, launchPreparedPlaygroundPlatform } from "@midscene/playground";
 import { AndroidAgent, AndroidDevice, getConnectedDevicesWithDetails } from "@midscene/android";
-import { PLAYGROUND_SERVER_PORT, SCRCPY_SERVER_PORT } from "@midscene/shared/constants";
+import { PLAYGROUND_SERVER_PORT, SCRCPY_PREVIEW_METADATA_TIMEOUT_MS, SCRCPY_PUSH_TIMEOUT_MS, SCRCPY_SERVER_PORT, SCRCPY_START_TIMEOUT_MS, SCRCPY_VIDEO_STREAM_TIMEOUT_MS } from "@midscene/shared/constants";
 import { findAvailablePort } from "@midscene/shared/node";
 import { exec } from "node:child_process";
 import { createReadStream } from "node:fs";
@@ -42,8 +42,8 @@ const androidPlaygroundPlatform = definePlaygroundPlatform({
             async getSetupSchema () {
                 const targets = await getAdbTargets();
                 return {
-                    title: 'Connect Android device',
-                    description: 'Select an available ADB device to create the current Android Agent.',
+                    title: 'Welcome to\nMidscene.js Playground!',
+                    description: 'Select an available ADB device to create the current Android Agent',
                     primaryActionLabel: 'Create Agent',
                     autoSubmitWhenReady: 1 === targets.length,
                     fields: [
@@ -129,6 +129,24 @@ const androidPlaygroundPlatform = definePlaygroundPlatform({
         };
     }
 });
+function getScrcpyPreviewStatusMessage(phase) {
+    switch(phase){
+        case 'connecting-device':
+            return 'Preparing Android device connection…';
+        case 'pushing-server':
+            return 'Uploading scrcpy runtime to device…';
+        case 'starting-service':
+            return 'Starting scrcpy service…';
+        case 'waiting-for-video':
+            return 'Waiting for first video frame…';
+    }
+}
+function buildScrcpyPreviewStatusEvent(phase) {
+    return {
+        phase,
+        message: getScrcpyPreviewStatusMessage(phase)
+    };
+}
 function _define_property(obj, key, value) {
     if (key in obj) Object.defineProperty(obj, key, {
         value: value,
@@ -139,6 +157,48 @@ function _define_property(obj, key, value) {
     else obj[key] = value;
     return obj;
 }
+class PromiseTimeoutError extends Error {
+    constructor(message, timeoutMs){
+        super(message), _define_property(this, "timeoutMs", void 0);
+        this.name = 'PromiseTimeoutError';
+        this.timeoutMs = timeoutMs;
+    }
+}
+function runTimeoutCallback(callback, context) {
+    if (!callback) return;
+    Promise.resolve().then(callback).catch((error)=>{
+        console.error(`Failed to run ${context}:`, error);
+    });
+}
+function withTimeout(promise, timeoutMs, message, options = {}) {
+    return new Promise((resolve, reject)=>{
+        let timedOut = false;
+        const timer = setTimeout(()=>{
+            timedOut = true;
+            runTimeoutCallback(options.onTimeout, 'timeout callback');
+            reject(new PromiseTimeoutError(message, timeoutMs));
+        }, timeoutMs);
+        Promise.resolve(promise).then((value)=>{
+            clearTimeout(timer);
+            if (timedOut) return void runTimeoutCallback(()=>options.onSettledAfterTimeout?.(value), 'post-timeout settle callback');
+            resolve(value);
+        }, (error)=>{
+            clearTimeout(timer);
+            if (timedOut) return void runTimeoutCallback(()=>options.onRejectedAfterTimeout?.(error), 'post-timeout rejection callback');
+            reject(error);
+        });
+    });
+}
+function scrcpy_server_define_property(obj, key, value) {
+    if (key in obj) Object.defineProperty(obj, key, {
+        value: value,
+        enumerable: true,
+        configurable: true,
+        writable: true
+    });
+    else obj[key] = value;
+    return obj;
+}
 const debugPage = getDebug('android:playground');
 const promiseExec = promisify(exec);
 const LOOPBACK_HOSTS = new Set([
@@ -249,14 +309,15 @@ class ScrcpyServer {
             return null;
         }
     }
-    async startScrcpy(adb, options = {}) {
+    async startScrcpy(adb, options = {}, onProgress) {
         const { AdbScrcpyClient, AdbScrcpyOptions3_3_3 } = await import("@yume-chan/adb-scrcpy");
         const { ReadableStream } = await import("@yume-chan/stream-extra");
         const { DefaultServerPath } = await import("@yume-chan/scrcpy");
         const currentDir = 'undefined' != typeof __dirname ? __dirname : node_path.dirname(fileURLToPath(import.meta.url));
         const serverBinPath = node_path.resolve(currentDir, '../../bin/scrcpy-server');
         try {
-            await AdbScrcpyClient.pushServer(adb, ReadableStream.from(createReadStream(serverBinPath)));
+            onProgress?.('pushing-server');
+            await withTimeout(AdbScrcpyClient.pushServer(adb, ReadableStream.from(createReadStream(serverBinPath))), SCRCPY_PUSH_TIMEOUT_MS, `Timed out pushing scrcpy server to device after ${Math.round(SCRCPY_PUSH_TIMEOUT_MS / 1000)}s`);
             const scrcpyOptions = new AdbScrcpyOptions3_3_3({
                 audio: false,
                 control: true,
@@ -265,7 +326,17 @@ class ScrcpyServer {
                 videoBitRate: 2000000,
                 ...options
             });
-            return await AdbScrcpyClient.start(adb, DefaultServerPath, scrcpyOptions);
+            onProgress?.('starting-service');
+            const startPromise = AdbScrcpyClient.start(adb, DefaultServerPath, scrcpyOptions);
+            return await withTimeout(startPromise, SCRCPY_START_TIMEOUT_MS, `Timed out starting scrcpy service after ${Math.round(SCRCPY_START_TIMEOUT_MS / 1000)}s`, {
+                onSettledAfterTimeout: async (lateClient)=>{
+                    try {
+                        await lateClient.close();
+                    } catch (closeError) {
+                        console.error('failed to close late scrcpy client after timeout:', closeError);
+                    }
+                }
+            });
         } catch (error) {
             console.error('failed to start scrcpy:', error);
             throw error;
@@ -276,6 +347,9 @@ class ScrcpyServer {
             debugPage('client connected, id: %s, client address: %s', socket.id, socket.handshake.address);
             let scrcpyClient = null;
             let adb = null;
+            const emitPreviewStatus = (phase)=>{
+                socket.emit('preview-status', buildScrcpyPreviewStatusEvent(phase));
+            };
             const sendDevicesList = async ()=>{
                 try {
                     debugPage('Socket request to get devices list');
@@ -324,6 +398,7 @@ class ScrcpyServer {
                 const { ScrcpyVideoCodecId } = await import("@yume-chan/scrcpy");
                 try {
                     debugPage('received device connection request, options: %s, client id: %s', options, socket.id);
+                    emitPreviewStatus('connecting-device');
                     adb = await this.getAdb(this.currentDeviceId || void 0);
                     if (!adb) {
                         console.error('no available device found');
@@ -333,7 +408,7 @@ class ScrcpyServer {
                         return;
                     }
                     debugPage('starting scrcpy service, device id: %s', this.currentDeviceId);
-                    scrcpyClient = await this.startScrcpy(adb, options);
+                    scrcpyClient = await this.startScrcpy(adb, options, emitPreviewStatus);
                     debugPage('scrcpy service started successfully');
                     debugPage('check scrcpyClient object structure: %s', Object.getOwnPropertyNames(scrcpyClient).map((name)=>{
                         const type = typeof scrcpyClient[name];
@@ -346,9 +421,11 @@ class ScrcpyServer {
                             let videoStream;
                             if ('object' == typeof scrcpyClient.videoStream && 'function' == typeof scrcpyClient.videoStream.then) {
                                 debugPage('videoStream is a Promise, waiting for resolution...');
-                                videoStream = await scrcpyClient.videoStream;
+                                emitPreviewStatus('waiting-for-video');
+                                videoStream = await withTimeout(scrcpyClient.videoStream, SCRCPY_VIDEO_STREAM_TIMEOUT_MS, `Timed out waiting for scrcpy video stream metadata after ${Math.round(SCRCPY_VIDEO_STREAM_TIMEOUT_MS / 1000)}s`);
                             } else {
                                 debugPage('videoStream is not a Promise, directly use');
+                                emitPreviewStatus('waiting-for-video');
                                 videoStream = scrcpyClient.videoStream;
                             }
                             debugPage('video stream fetched successfully, metadata: %s', videoStream.metadata);
@@ -365,7 +442,7 @@ class ScrcpyServer {
                             }
                             debugPage('prepare to send video-metadata event to client, data: %s', JSON.stringify(metadata));
                             socket.emit('video-metadata', metadata);
-                            debugPage('video-metadata event sent to client, id: %s', socket.id);
+                            debugPage('video-metadata event sent to client, id: %s, timeout budget: %ss', socket.id, Math.round(SCRCPY_PREVIEW_METADATA_TIMEOUT_MS / 1000));
                             const { stream } = videoStream;
                             const reader = stream.getReader();
                             const processStream = async ()=>{
@@ -404,6 +481,14 @@ class ScrcpyServer {
                     if (scrcpyClient?.controller) socket.emit('control-ready');
                 } catch (error) {
                     console.error('failed to connect device:', error);
+                    if (scrcpyClient) {
+                        try {
+                            await scrcpyClient.close();
+                        } catch (closeError) {
+                            console.error('failed to close scrcpy client after error:', closeError);
+                        }
+                        scrcpyClient = null;
+                    }
                     socket.emit('error', {
                         message: `Failed to connect device: ${error?.message || 'Unknown error'}`
                     });
@@ -467,15 +552,15 @@ class ScrcpyServer {
         if (this.httpServer) return this.httpServer.close();
     }
     constructor(){
-        _define_property(this, "app", void 0);
-        _define_property(this, "httpServer", void 0);
-        _define_property(this, "io", void 0);
-        _define_property(this, "port", void 0);
-        _define_property(this, "defaultPort", SCRCPY_SERVER_PORT);
-        _define_property(this, "adbClient", null);
-        _define_property(this, "currentDeviceId", null);
-        _define_property(this, "devicePollInterval", null);
-        _define_property(this, "lastDeviceList", '');
+        scrcpy_server_define_property(this, "app", void 0);
+        scrcpy_server_define_property(this, "httpServer", void 0);
+        scrcpy_server_define_property(this, "io", void 0);
+        scrcpy_server_define_property(this, "port", void 0);
+        scrcpy_server_define_property(this, "defaultPort", SCRCPY_SERVER_PORT);
+        scrcpy_server_define_property(this, "adbClient", null);
+        scrcpy_server_define_property(this, "currentDeviceId", null);
+        scrcpy_server_define_property(this, "devicePollInterval", null);
+        scrcpy_server_define_property(this, "lastDeviceList", '');
         this.app = express();
         this.httpServer = createServer(this.app);
         this.io = new Server(this.httpServer, {

package/dist/es/index.mjs

@@ -1,7 +1,7 @@
 import node_path from "node:path";
 import { AndroidAgent, AndroidDevice, getConnectedDevicesWithDetails } from "@midscene/android";
 import { createScrcpyPreviewDescriptor, definePlaygroundPlatform } from "@midscene/playground";
-import { PLAYGROUND_SERVER_PORT, SCRCPY_SERVER_PORT } from "@midscene/shared/constants";
+import { PLAYGROUND_SERVER_PORT, SCRCPY_PREVIEW_METADATA_TIMEOUT_MS, SCRCPY_PUSH_TIMEOUT_MS, SCRCPY_SERVER_PORT, SCRCPY_START_TIMEOUT_MS, SCRCPY_VIDEO_STREAM_TIMEOUT_MS } from "@midscene/shared/constants";
 import { findAvailablePort } from "@midscene/shared/node";
 import { exec } from "node:child_process";
 import { createReadStream } from "node:fs";
@@ -42,8 +42,8 @@ const androidPlaygroundPlatform = definePlaygroundPlatform({
             async getSetupSchema () {
                 const targets = await getAdbTargets();
                 return {
-                    title: 'Connect Android device',
-                    description: 'Select an available ADB device to create the current Android Agent.',
+                    title: 'Welcome to\nMidscene.js Playground!',
+                    description: 'Select an available ADB device to create the current Android Agent',
                     primaryActionLabel: 'Create Agent',
                     autoSubmitWhenReady: 1 === targets.length,
                     fields: [
@@ -129,6 +129,24 @@ const androidPlaygroundPlatform = definePlaygroundPlatform({
         };
     }
 });
+function getScrcpyPreviewStatusMessage(phase) {
+    switch(phase){
+        case 'connecting-device':
+            return 'Preparing Android device connection…';
+        case 'pushing-server':
+            return 'Uploading scrcpy runtime to device…';
+        case 'starting-service':
+            return 'Starting scrcpy service…';
+        case 'waiting-for-video':
+            return 'Waiting for first video frame…';
+    }
+}
+function buildScrcpyPreviewStatusEvent(phase) {
+    return {
+        phase,
+        message: getScrcpyPreviewStatusMessage(phase)
+    };
+}
 function _define_property(obj, key, value) {
     if (key in obj) Object.defineProperty(obj, key, {
         value: value,
@@ -139,6 +157,48 @@ function _define_property(obj, key, value) {
     else obj[key] = value;
     return obj;
 }
+class PromiseTimeoutError extends Error {
+    constructor(message, timeoutMs){
+        super(message), _define_property(this, "timeoutMs", void 0);
+        this.name = 'PromiseTimeoutError';
+        this.timeoutMs = timeoutMs;
+    }
+}
+function runTimeoutCallback(callback, context) {
+    if (!callback) return;
+    Promise.resolve().then(callback).catch((error)=>{
+        console.error(`Failed to run ${context}:`, error);
+    });
+}
+function withTimeout(promise, timeoutMs, message, options = {}) {
+    return new Promise((resolve, reject)=>{
+        let timedOut = false;
+        const timer = setTimeout(()=>{
+            timedOut = true;
+            runTimeoutCallback(options.onTimeout, 'timeout callback');
+            reject(new PromiseTimeoutError(message, timeoutMs));
+        }, timeoutMs);
+        Promise.resolve(promise).then((value)=>{
+            clearTimeout(timer);
+            if (timedOut) return void runTimeoutCallback(()=>options.onSettledAfterTimeout?.(value), 'post-timeout settle callback');
+            resolve(value);
+        }, (error)=>{
+            clearTimeout(timer);
+            if (timedOut) return void runTimeoutCallback(()=>options.onRejectedAfterTimeout?.(error), 'post-timeout rejection callback');
+            reject(error);
+        });
+    });
+}
+function scrcpy_server_define_property(obj, key, value) {
+    if (key in obj) Object.defineProperty(obj, key, {
+        value: value,
+        enumerable: true,
+        configurable: true,
+        writable: true
+    });
+    else obj[key] = value;
+    return obj;
+}
 const debugPage = getDebug('android:playground');
 const promiseExec = promisify(exec);
 const LOOPBACK_HOSTS = new Set([
@@ -249,14 +309,15 @@ class ScrcpyServer {
             return null;
         }
     }
-    async startScrcpy(adb, options = {}) {
+    async startScrcpy(adb, options = {}, onProgress) {
         const { AdbScrcpyClient, AdbScrcpyOptions3_3_3 } = await import("@yume-chan/adb-scrcpy");
         const { ReadableStream } = await import("@yume-chan/stream-extra");
         const { DefaultServerPath } = await import("@yume-chan/scrcpy");
         const currentDir = 'undefined' != typeof __dirname ? __dirname : node_path.dirname(fileURLToPath(import.meta.url));
         const serverBinPath = node_path.resolve(currentDir, '../../bin/scrcpy-server');
         try {
-            await AdbScrcpyClient.pushServer(adb, ReadableStream.from(createReadStream(serverBinPath)));
+            onProgress?.('pushing-server');
+            await withTimeout(AdbScrcpyClient.pushServer(adb, ReadableStream.from(createReadStream(serverBinPath))), SCRCPY_PUSH_TIMEOUT_MS, `Timed out pushing scrcpy server to device after ${Math.round(SCRCPY_PUSH_TIMEOUT_MS / 1000)}s`);
             const scrcpyOptions = new AdbScrcpyOptions3_3_3({
                 audio: false,
                 control: true,
@@ -265,7 +326,17 @@ class ScrcpyServer {
                 videoBitRate: 2000000,
                 ...options
             });
-            return await AdbScrcpyClient.start(adb, DefaultServerPath, scrcpyOptions);
+            onProgress?.('starting-service');
+            const startPromise = AdbScrcpyClient.start(adb, DefaultServerPath, scrcpyOptions);
+            return await withTimeout(startPromise, SCRCPY_START_TIMEOUT_MS, `Timed out starting scrcpy service after ${Math.round(SCRCPY_START_TIMEOUT_MS / 1000)}s`, {
+                onSettledAfterTimeout: async (lateClient)=>{
+                    try {
+                        await lateClient.close();
+                    } catch (closeError) {
+                        console.error('failed to close late scrcpy client after timeout:', closeError);
+                    }
+                }
+            });
         } catch (error) {
             console.error('failed to start scrcpy:', error);
             throw error;
@@ -276,6 +347,9 @@ class ScrcpyServer {
             debugPage('client connected, id: %s, client address: %s', socket.id, socket.handshake.address);
             let scrcpyClient = null;
             let adb = null;
+            const emitPreviewStatus = (phase)=>{
+                socket.emit('preview-status', buildScrcpyPreviewStatusEvent(phase));
+            };
             const sendDevicesList = async ()=>{
                 try {
                     debugPage('Socket request to get devices list');
@@ -324,6 +398,7 @@ class ScrcpyServer {
                 const { ScrcpyVideoCodecId } = await import("@yume-chan/scrcpy");
                 try {
                     debugPage('received device connection request, options: %s, client id: %s', options, socket.id);
+                    emitPreviewStatus('connecting-device');
                     adb = await this.getAdb(this.currentDeviceId || void 0);
                     if (!adb) {
                         console.error('no available device found');
@@ -333,7 +408,7 @@ class ScrcpyServer {
                         return;
                     }
                     debugPage('starting scrcpy service, device id: %s', this.currentDeviceId);
-                    scrcpyClient = await this.startScrcpy(adb, options);
+                    scrcpyClient = await this.startScrcpy(adb, options, emitPreviewStatus);
                     debugPage('scrcpy service started successfully');
                     debugPage('check scrcpyClient object structure: %s', Object.getOwnPropertyNames(scrcpyClient).map((name)=>{
                         const type = typeof scrcpyClient[name];
@@ -346,9 +421,11 @@ class ScrcpyServer {
                             let videoStream;
                             if ('object' == typeof scrcpyClient.videoStream && 'function' == typeof scrcpyClient.videoStream.then) {
                                 debugPage('videoStream is a Promise, waiting for resolution...');
-                                videoStream = await scrcpyClient.videoStream;
+                                emitPreviewStatus('waiting-for-video');
+                                videoStream = await withTimeout(scrcpyClient.videoStream, SCRCPY_VIDEO_STREAM_TIMEOUT_MS, `Timed out waiting for scrcpy video stream metadata after ${Math.round(SCRCPY_VIDEO_STREAM_TIMEOUT_MS / 1000)}s`);
                             } else {
                                 debugPage('videoStream is not a Promise, directly use');
+                                emitPreviewStatus('waiting-for-video');
                                 videoStream = scrcpyClient.videoStream;
                             }
                             debugPage('video stream fetched successfully, metadata: %s', videoStream.metadata);
@@ -365,7 +442,7 @@ class ScrcpyServer {
                             }
                             debugPage('prepare to send video-metadata event to client, data: %s', JSON.stringify(metadata));
                             socket.emit('video-metadata', metadata);
-                            debugPage('video-metadata event sent to client, id: %s', socket.id);
+                            debugPage('video-metadata event sent to client, id: %s, timeout budget: %ss', socket.id, Math.round(SCRCPY_PREVIEW_METADATA_TIMEOUT_MS / 1000));
                             const { stream } = videoStream;
                             const reader = stream.getReader();
                             const processStream = async ()=>{
@@ -404,6 +481,14 @@ class ScrcpyServer {
                     if (scrcpyClient?.controller) socket.emit('control-ready');
                 } catch (error) {
                     console.error('failed to connect device:', error);
+                    if (scrcpyClient) {
+                        try {
+                            await scrcpyClient.close();
+                        } catch (closeError) {
+                            console.error('failed to close scrcpy client after error:', closeError);
+                        }
+                        scrcpyClient = null;
+                    }
                     socket.emit('error', {
                         message: `Failed to connect device: ${error?.message || 'Unknown error'}`
                     });
@@ -467,15 +552,15 @@ class ScrcpyServer {
         if (this.httpServer) return this.httpServer.close();
     }
     constructor(){
-        _define_property(this, "app", void 0);
-        _define_property(this, "httpServer", void 0);
-        _define_property(this, "io", void 0);
-        _define_property(this, "port", void 0);
-        _define_property(this, "defaultPort", SCRCPY_SERVER_PORT);
-        _define_property(this, "adbClient", null);
-        _define_property(this, "currentDeviceId", null);
-        _define_property(this, "devicePollInterval", null);
-        _define_property(this, "lastDeviceList", '');
+        scrcpy_server_define_property(this, "app", void 0);
+        scrcpy_server_define_property(this, "httpServer", void 0);
+        scrcpy_server_define_property(this, "io", void 0);
+        scrcpy_server_define_property(this, "port", void 0);
+        scrcpy_server_define_property(this, "defaultPort", SCRCPY_SERVER_PORT);
+        scrcpy_server_define_property(this, "adbClient", null);
+        scrcpy_server_define_property(this, "currentDeviceId", null);
+        scrcpy_server_define_property(this, "devicePollInterval", null);
+        scrcpy_server_define_property(this, "lastDeviceList", '');
         this.app = express();
         this.httpServer = createServer(this.app);
         this.io = new Server(this.httpServer, {

package/dist/lib/bin.js

@@ -57,8 +57,8 @@ const androidPlaygroundPlatform = (0, playground_namespaceObject.definePlaygroun
             async getSetupSchema () {
                 const targets = await getAdbTargets();
                 return {
-                    title: 'Connect Android device',
-                    description: 'Select an available ADB device to create the current Android Agent.',
+                    title: 'Welcome to\nMidscene.js Playground!',
+                    description: 'Select an available ADB device to create the current Android Agent',
                     primaryActionLabel: 'Create Agent',
                     autoSubmitWhenReady: 1 === targets.length,
                     fields: [
@@ -155,6 +155,24 @@ var external_cors_default = /*#__PURE__*/ __webpack_require__.n(external_cors_na
 const external_express_namespaceObject = require("express");
 var external_express_default = /*#__PURE__*/ __webpack_require__.n(external_express_namespaceObject);
 const external_socket_io_namespaceObject = require("socket.io");
+function getScrcpyPreviewStatusMessage(phase) {
+    switch(phase){
+        case 'connecting-device':
+            return 'Preparing Android device connection…';
+        case 'pushing-server':
+            return 'Uploading scrcpy runtime to device…';
+        case 'starting-service':
+            return 'Starting scrcpy service…';
+        case 'waiting-for-video':
+            return 'Waiting for first video frame…';
+    }
+}
+function buildScrcpyPreviewStatusEvent(phase) {
+    return {
+        phase,
+        message: getScrcpyPreviewStatusMessage(phase)
+    };
+}
 function _define_property(obj, key, value) {
     if (key in obj) Object.defineProperty(obj, key, {
         value: value,
@@ -165,6 +183,48 @@ function _define_property(obj, key, value) {
     else obj[key] = value;
     return obj;
 }
+class PromiseTimeoutError extends Error {
+    constructor(message, timeoutMs){
+        super(message), _define_property(this, "timeoutMs", void 0);
+        this.name = 'PromiseTimeoutError';
+        this.timeoutMs = timeoutMs;
+    }
+}
+function runTimeoutCallback(callback, context) {
+    if (!callback) return;
+    Promise.resolve().then(callback).catch((error)=>{
+        console.error(`Failed to run ${context}:`, error);
+    });
+}
+function withTimeout(promise, timeoutMs, message, options = {}) {
+    return new Promise((resolve, reject)=>{
+        let timedOut = false;
+        const timer = setTimeout(()=>{
+            timedOut = true;
+            runTimeoutCallback(options.onTimeout, 'timeout callback');
+            reject(new PromiseTimeoutError(message, timeoutMs));
+        }, timeoutMs);
+        Promise.resolve(promise).then((value)=>{
+            clearTimeout(timer);
+            if (timedOut) return void runTimeoutCallback(()=>options.onSettledAfterTimeout?.(value), 'post-timeout settle callback');
+            resolve(value);
+        }, (error)=>{
+            clearTimeout(timer);
+            if (timedOut) return void runTimeoutCallback(()=>options.onRejectedAfterTimeout?.(error), 'post-timeout rejection callback');
+            reject(error);
+        });
+    });
+}
+function scrcpy_server_define_property(obj, key, value) {
+    if (key in obj) Object.defineProperty(obj, key, {
+        value: value,
+        enumerable: true,
+        configurable: true,
+        writable: true
+    });
+    else obj[key] = value;
+    return obj;
+}
 const debugPage = (0, logger_namespaceObject.getDebug)('android:playground');
 const promiseExec = (0, external_node_util_namespaceObject.promisify)(external_node_child_process_namespaceObject.exec);
 const LOOPBACK_HOSTS = new Set([
@@ -275,14 +335,15 @@ class ScrcpyServer {
             return null;
         }
     }
-    async startScrcpy(adb, options = {}) {
+    async startScrcpy(adb, options = {}, onProgress) {
         const { AdbScrcpyClient, AdbScrcpyOptions3_3_3 } = await import("@yume-chan/adb-scrcpy");
         const { ReadableStream } = await import("@yume-chan/stream-extra");
         const { DefaultServerPath } = await import("@yume-chan/scrcpy");
         const currentDir = __dirname;
         const serverBinPath = external_node_path_default().resolve(currentDir, '../../bin/scrcpy-server');
         try {
-            await AdbScrcpyClient.pushServer(adb, ReadableStream.from((0, external_node_fs_namespaceObject.createReadStream)(serverBinPath)));
+            onProgress?.('pushing-server');
+            await withTimeout(AdbScrcpyClient.pushServer(adb, ReadableStream.from((0, external_node_fs_namespaceObject.createReadStream)(serverBinPath))), constants_namespaceObject.SCRCPY_PUSH_TIMEOUT_MS, `Timed out pushing scrcpy server to device after ${Math.round(constants_namespaceObject.SCRCPY_PUSH_TIMEOUT_MS / 1000)}s`);
             const scrcpyOptions = new AdbScrcpyOptions3_3_3({
                 audio: false,
                 control: true,
@@ -291,7 +352,17 @@ class ScrcpyServer {
                 videoBitRate: 2000000,
                 ...options
             });
-            return await AdbScrcpyClient.start(adb, DefaultServerPath, scrcpyOptions);
+            onProgress?.('starting-service');
+            const startPromise = AdbScrcpyClient.start(adb, DefaultServerPath, scrcpyOptions);
+            return await withTimeout(startPromise, constants_namespaceObject.SCRCPY_START_TIMEOUT_MS, `Timed out starting scrcpy service after ${Math.round(constants_namespaceObject.SCRCPY_START_TIMEOUT_MS / 1000)}s`, {
+                onSettledAfterTimeout: async (lateClient)=>{
+                    try {
+                        await lateClient.close();
+                    } catch (closeError) {
+                        console.error('failed to close late scrcpy client after timeout:', closeError);
+                    }
+                }
+            });
         } catch (error) {
             console.error('failed to start scrcpy:', error);
             throw error;
@@ -302,6 +373,9 @@ class ScrcpyServer {
             debugPage('client connected, id: %s, client address: %s', socket.id, socket.handshake.address);
             let scrcpyClient = null;
             let adb = null;
+            const emitPreviewStatus = (phase)=>{
+                socket.emit('preview-status', buildScrcpyPreviewStatusEvent(phase));
+            };
             const sendDevicesList = async ()=>{
                 try {
                     debugPage('Socket request to get devices list');
@@ -350,6 +424,7 @@ class ScrcpyServer {
                 const { ScrcpyVideoCodecId } = await import("@yume-chan/scrcpy");
                 try {
                     debugPage('received device connection request, options: %s, client id: %s', options, socket.id);
+                    emitPreviewStatus('connecting-device');
                     adb = await this.getAdb(this.currentDeviceId || void 0);
                     if (!adb) {
                         console.error('no available device found');
@@ -359,7 +434,7 @@ class ScrcpyServer {
                         return;
                     }
                     debugPage('starting scrcpy service, device id: %s', this.currentDeviceId);
-                    scrcpyClient = await this.startScrcpy(adb, options);
+                    scrcpyClient = await this.startScrcpy(adb, options, emitPreviewStatus);
                     debugPage('scrcpy service started successfully');
                     debugPage('check scrcpyClient object structure: %s', Object.getOwnPropertyNames(scrcpyClient).map((name)=>{
                         const type = typeof scrcpyClient[name];
@@ -372,9 +447,11 @@ class ScrcpyServer {
                             let videoStream;
                             if ('object' == typeof scrcpyClient.videoStream && 'function' == typeof scrcpyClient.videoStream.then) {
                                 debugPage('videoStream is a Promise, waiting for resolution...');
-                                videoStream = await scrcpyClient.videoStream;
+                                emitPreviewStatus('waiting-for-video');
+                                videoStream = await withTimeout(scrcpyClient.videoStream, constants_namespaceObject.SCRCPY_VIDEO_STREAM_TIMEOUT_MS, `Timed out waiting for scrcpy video stream metadata after ${Math.round(constants_namespaceObject.SCRCPY_VIDEO_STREAM_TIMEOUT_MS / 1000)}s`);
                             } else {
                                 debugPage('videoStream is not a Promise, directly use');
+                                emitPreviewStatus('waiting-for-video');
                                 videoStream = scrcpyClient.videoStream;
                             }
                             debugPage('video stream fetched successfully, metadata: %s', videoStream.metadata);
@@ -391,7 +468,7 @@ class ScrcpyServer {
                             }
                             debugPage('prepare to send video-metadata event to client, data: %s', JSON.stringify(metadata));
                             socket.emit('video-metadata', metadata);
-                            debugPage('video-metadata event sent to client, id: %s', socket.id);
+                            debugPage('video-metadata event sent to client, id: %s, timeout budget: %ss', socket.id, Math.round(constants_namespaceObject.SCRCPY_PREVIEW_METADATA_TIMEOUT_MS / 1000));
                             const { stream } = videoStream;
                             const reader = stream.getReader();
                             const processStream = async ()=>{
@@ -430,6 +507,14 @@ class ScrcpyServer {
                     if (scrcpyClient?.controller) socket.emit('control-ready');
                 } catch (error) {
                     console.error('failed to connect device:', error);
+                    if (scrcpyClient) {
+                        try {
+                            await scrcpyClient.close();
+                        } catch (closeError) {
+                            console.error('failed to close scrcpy client after error:', closeError);
+                        }
+                        scrcpyClient = null;
+                    }
                     socket.emit('error', {
                         message: `Failed to connect device: ${error?.message || 'Unknown error'}`
                     });
@@ -493,15 +578,15 @@ class ScrcpyServer {
         if (this.httpServer) return this.httpServer.close();
     }
     constructor(){
-        _define_property(this, "app", void 0);
-        _define_property(this, "httpServer", void 0);
-        _define_property(this, "io", void 0);
-        _define_property(this, "port", void 0);
-        _define_property(this, "defaultPort", constants_namespaceObject.SCRCPY_SERVER_PORT);
-        _define_property(this, "adbClient", null);
-        _define_property(this, "currentDeviceId", null);
-        _define_property(this, "devicePollInterval", null);
-        _define_property(this, "lastDeviceList", '');
+        scrcpy_server_define_property(this, "app", void 0);
+        scrcpy_server_define_property(this, "httpServer", void 0);
+        scrcpy_server_define_property(this, "io", void 0);
+        scrcpy_server_define_property(this, "port", void 0);
+        scrcpy_server_define_property(this, "defaultPort", constants_namespaceObject.SCRCPY_SERVER_PORT);
+        scrcpy_server_define_property(this, "adbClient", null);
+        scrcpy_server_define_property(this, "currentDeviceId", null);
+        scrcpy_server_define_property(this, "devicePollInterval", null);
+        scrcpy_server_define_property(this, "lastDeviceList", '');
         this.app = external_express_default()();
         this.httpServer = (0, external_node_http_namespaceObject.createServer)(this.app);
         this.io = new external_socket_io_namespaceObject.Server(this.httpServer, {