@midscene/android 1.10.9 → 1.10.10-beta-20260805080137.0

package/dist/es/index.mjs

@@ -17,8 +17,10 @@ import { BaseMidsceneTools } from "@midscene/shared/agent-tools/base-tools";
 var __webpack_modules__ = {
     "./src/scrcpy-manager.ts" (__unused_rspack_module, __webpack_exports__, __webpack_require__) {
         __webpack_require__.d(__webpack_exports__, {
+            GJ: ()=>isScrcpyFreshFrameUnavailableError,
             ScrcpyScreenshotManager: ()=>ScrcpyScreenshotManager,
-            o: ()=>DEFAULT_SCRCPY_CONFIG
+            Xr: ()=>SCRCPY_VIDEO_BIT_RATE_NETWORK_HINT,
+            ov: ()=>DEFAULT_SCRCPY_CONFIG
         });
         var node_fs__rspack_import_0 = __webpack_require__("node:fs");
         var node_module__rspack_import_1 = __webpack_require__("node:module");
@@ -53,6 +55,14 @@ var __webpack_modules__ = {
         const CONNECTION_WAIT_MS = 1000;
         const MAX_SERVER_OUTPUT_LINES = 100;
         const SERVER_OUTPUT_DRAIN_TIMEOUT_MS = 500;
+        const MAX_FRAME_AGE_US = 500000n;
+        const FRAME_FRESHNESS_WARN_INTERVAL_MS = 5000;
+        const TRANSPORT_BACKLOG_WARN_INTERVAL_MS = 5000;
+        const DEVICE_UPTIME_COMMAND = [
+            'dumpsys',
+            'power'
+        ];
+        const SCRCPY_VIDEO_BIT_RATE_NETWORK_HINT = 'The appropriate scrcpy video bitrate depends on network conditions. For constrained remote links, consider setting scrcpyConfig.videoBitRate to 4_000_000 (4 Mbps) as a starting point, and lower it further if backlog persists.';
         const BUSY_LOOP_WINDOW_MS = 1000;
         const BUSY_LOOP_MAX_READS = 500;
         const BUSY_LOOP_COOLDOWN_MS = 50;
@@ -63,6 +73,24 @@ var __webpack_modules__ = {
             idleTimeoutMs: DEFAULT_IDLE_TIMEOUT_MS,
             videoBitRate: DEFAULT_VIDEO_BIT_RATE
         };
+        const SCRCPY_FRESH_FRAME_UNAVAILABLE_ERROR_CODE = 'ERR_SCRCPY_FRESH_FRAME_UNAVAILABLE';
+        class ScrcpyFreshFrameUnavailableError extends Error {
+            constructor(message, options){
+                super(message, options), _define_property(this, "code", SCRCPY_FRESH_FRAME_UNAVAILABLE_ERROR_CODE);
+                this.name = 'ScrcpyFreshFrameUnavailableError';
+            }
+        }
+        function isScrcpyFreshFrameUnavailableError(error) {
+            return 'object' == typeof error && null !== error && 'code' in error && error.code === SCRCPY_FRESH_FRAME_UNAVAILABLE_ERROR_CODE;
+        }
+        function parseDeviceUptimeMs(output) {
+            const match = output.match(/mLastWakeTime=(\d+)\s+\((?:(\d+) ms ago|in (\d+) ms|now)\)/);
+            if (!match) throw new Error(`Unable to read Android device uptime from dumpsys power: ${output.trim() || '<empty output>'}`);
+            const referenceMs = BigInt(match[1]);
+            if (match[2]) return referenceMs + BigInt(match[2]);
+            if (match[3]) return referenceMs - BigInt(match[3]);
+            return referenceMs;
+        }
         function isKeyFrameNalType(nalUnitType) {
             return nalUnitType === NAL_TYPE_IDR || nalUnitType === NAL_TYPE_SPS || nalUnitType === NAL_TYPE_PPS;
         }
@@ -245,24 +273,25 @@ var __webpack_modules__ = {
                     debugScrcpy(`Received SPS/PPS configuration: ${this.spsHeader.length}B`);
                     return;
                 }
+                const receivedAtUs = this.monotonicTimeUs();
+                if (!this.isFrameFresh(packet.pts)) return;
                 const frameBuffer = Buffer.from(packet.data);
                 const isKeyFrame = detectH264KeyFrame(frameBuffer);
                 if (isKeyFrame && this.spsHeader) {
+                    const timing = this.estimateFrameTiming(packet.pts, receivedAtUs);
                     this.lastRawKeyframe = frameBuffer;
-                    this.lastRawKeyframeAt = Date.now();
-                    if (this.keyframeResolvers.length > 0) {
-                        const combined = Buffer.concat([
-                            this.spsHeader,
-                            frameBuffer
-                        ]);
-                        this.notifyKeyframeWaiters(combined);
-                    }
-                    if (this.keyframeListeners.size > 0) {
-                        const frame = {
-                            data: frameBuffer,
-                            header: this.spsHeader,
-                            capturedAt: this.lastRawKeyframeAt
-                        };
+                    this.lastRawKeyframeAt = timing.capturedAt;
+                    this.lastRawKeyframePtsUs = packet.pts;
+                    this.lastRawKeyframeEstimatedAgeMs = timing.estimatedAgeMs;
+                    const frame = {
+                        data: frameBuffer,
+                        header: this.spsHeader,
+                        ptsUs: packet.pts,
+                        estimatedAgeMs: timing.estimatedAgeMs,
+                        capturedAt: this.lastRawKeyframeAt
+                    };
+                    if (this.keyframeResolvers.length > 0) this.notifyKeyframeWaiters(frame);
+                    if (this.keyframeListeners.size > 0 && this.isFrameAgeAcceptable(packet.pts, receivedAtUs)) {
                         for (const listener of this.keyframeListeners)try {
                             listener(frame);
                         } catch (error) {
@@ -272,6 +301,159 @@ var __webpack_modules__ = {
                     }
                 }
             }
+            async readDeviceClockCalibration() {
+                const startedAtUs = this.monotonicTimeUs();
+                const startedAtWallMs = Date.now();
+                const shellProtocol = this.adb.subprocess.shellProtocol;
+                let output;
+                if (shellProtocol) {
+                    const result = await shellProtocol.spawnWaitText(DEVICE_UPTIME_COMMAND);
+                    if (0 !== result.exitCode) throw new Error(`Unable to read Android device uptime (exit ${result.exitCode}): ${result.stderr.trim() || result.stdout.trim()}`);
+                    output = result.stdout;
+                } else output = await this.adb.subprocess.noneProtocol.spawnWaitText(DEVICE_UPTIME_COMMAND);
+                const finishedAtUs = this.monotonicTimeUs();
+                const finishedAtWallMs = Date.now();
+                return {
+                    deviceUptimeUs: 1000n * parseDeviceUptimeMs(output),
+                    hostMonotonicUs: startedAtUs + (finishedAtUs - startedAtUs) / 2n,
+                    hostWallTimeMs: startedAtWallMs + (finishedAtWallMs - startedAtWallMs) / 2,
+                    roundTripUs: finishedAtUs - startedAtUs
+                };
+            }
+            async ensureFrameClockCalibration() {
+                if (this.deviceClockCalibration) return;
+                this.deviceClockCalibration = await this.readDeviceClockCalibration();
+                debugScrcpy(`Calibrated scrcpy frame clock (RTT=${Number(this.deviceClockCalibration.roundTripUs / 1000n)}ms)`);
+            }
+            async setFreshnessBarrier(reason) {
+                const generation = ++this.frameFreshnessBarrierGeneration;
+                this.frameFreshnessBarrierPending = true;
+                this.clearFrameCache();
+                try {
+                    const calibration = await this.readDeviceClockCalibration();
+                    const barrierPtsUs = (calibration.deviceUptimeUs / 1000n + 1n) * 1000n;
+                    if (generation !== this.frameFreshnessBarrierGeneration) return this.frameFreshnessBarrierPtsUs ?? barrierPtsUs;
+                    this.deviceClockCalibration = calibration;
+                    this.frameFreshnessBarrierPtsUs = null === this.frameFreshnessBarrierPtsUs || barrierPtsUs > this.frameFreshnessBarrierPtsUs ? barrierPtsUs : this.frameFreshnessBarrierPtsUs;
+                    this.frameFreshnessBarrierReason = reason;
+                    this.frameFreshnessBarrierPending = false;
+                    this.frameFreshnessError = null;
+                    this.lastFramePtsUs = null;
+                    this.clearFrameCache();
+                    debugScrcpy(`Armed frame freshness barrier at PTS ${this.frameFreshnessBarrierPtsUs}µs (${reason}, clock RTT=${Number(calibration.roundTripUs / 1000n)}ms)`);
+                    return this.frameFreshnessBarrierPtsUs;
+                } catch (error) {
+                    if (generation === this.frameFreshnessBarrierGeneration) {
+                        this.frameFreshnessBarrierPending = false;
+                        this.frameFreshnessError = new Error(`Unable to establish scrcpy frame freshness barrier (${reason}): ${error instanceof Error ? error.message : String(error)}`, {
+                            cause: error
+                        });
+                    }
+                    throw this.frameFreshnessError ?? error;
+                }
+            }
+            isFrameFresh(packetPtsUs) {
+                if (this.frameFreshnessBarrierPending) return false;
+                if (void 0 !== packetPtsUs) {
+                    if (null !== this.lastFramePtsUs && packetPtsUs < this.lastFramePtsUs) {
+                        this.frameFreshnessError = new Error('Scrcpy frame PTS moved backwards; refusing frames until the device clock barrier is refreshed');
+                        this.frameFreshnessBarrierPending = true;
+                        this.clearFrameCache();
+                        this.warnFrameFreshness();
+                        return false;
+                    }
+                    this.lastFramePtsUs = packetPtsUs;
+                }
+                if (null === this.frameFreshnessBarrierPtsUs) return true;
+                if (void 0 === packetPtsUs) {
+                    this.frameFreshnessError = new Error('Scrcpy frame has no PTS metadata; cannot prove that it is newer than the freshness barrier');
+                    this.warnFrameFreshness();
+                    return false;
+                }
+                if (packetPtsUs >= this.frameFreshnessBarrierPtsUs) {
+                    if (this.frameFreshnessError) debugScrcpy(`Scrcpy video crossed the ${this.frameFreshnessBarrierReason ?? 'active'} freshness barrier at PTS ${packetPtsUs}µs`);
+                    this.frameFreshnessError = null;
+                    return true;
+                }
+                const behindBarrierUs = this.frameFreshnessBarrierPtsUs - packetPtsUs;
+                this.frameFreshnessError = new Error(`Scrcpy frame predates the ${this.frameFreshnessBarrierReason ?? 'active'} freshness barrier by ${Number(behindBarrierUs) / 1000}ms; refusing to use it`);
+                this.clearFrameCache();
+                this.warnFrameFreshness();
+                return false;
+            }
+            estimateFrameAgeUs(packetPtsUs, hostMonotonicUs = this.monotonicTimeUs()) {
+                const calibration = this.deviceClockCalibration;
+                if (void 0 === packetPtsUs || !calibration) return null;
+                const estimatedDeviceNowUs = calibration.deviceUptimeUs + (hostMonotonicUs - calibration.hostMonotonicUs);
+                return estimatedDeviceNowUs > packetPtsUs ? estimatedDeviceNowUs - packetPtsUs : 0n;
+            }
+            isFrameAgeAcceptable(packetPtsUs, hostMonotonicUs = this.monotonicTimeUs()) {
+                const ageUs = this.estimateFrameAgeUs(packetPtsUs, hostMonotonicUs);
+                if (null === ageUs) {
+                    this.frameFreshnessError = new Error(void 0 === packetPtsUs ? 'Scrcpy frame has no PTS metadata; cannot prove its absolute age' : 'Scrcpy frame clock is not calibrated; cannot prove its absolute age');
+                    this.warnFrameFreshness();
+                    return false;
+                }
+                if (ageUs <= MAX_FRAME_AGE_US) {
+                    if (this.frameFreshnessError) {
+                        debugScrcpy(`Scrcpy frame age recovered (${Number(ageUs / 1000n)}ms)`);
+                        this.frameFreshnessError = null;
+                    }
+                    return true;
+                }
+                this.frameFreshnessError = new Error(`Scrcpy frame absolute age is ${Number(ageUs / 1000n)}ms, exceeding the ${Number(MAX_FRAME_AGE_US / 1000n)}ms limit`);
+                this.warnFrameFreshness();
+                return false;
+            }
+            warnFrameFreshness() {
+                if (!this.frameFreshnessError) return;
+                const now = Date.now();
+                if (now - this.lastFrameFreshnessWarningAt >= FRAME_FRESHNESS_WARN_INTERVAL_MS) {
+                    warnScrcpy(this.frameFreshnessError.message);
+                    this.lastFrameFreshnessWarningAt = now;
+                }
+            }
+            warnTransportBacklog(error) {
+                const now = Date.now();
+                if (now - this.lastTransportBacklogWarningAt < TRANSPORT_BACKLOG_WARN_INTERVAL_MS) return;
+                const cause = this.frameFreshnessError ?? error;
+                const causeMessage = cause instanceof Error ? cause.message : String(cause);
+                const currentBitRateMbps = this.options.videoBitRate / 1000000;
+                warnScrcpy(`No usable scrcpy frame crossed the active freshness target within ${FRESH_FRAME_TIMEOUT_MS}ms; closing the stale stream epoch and falling back to ADB screenshot. This may indicate transport backlog or a static screen that emitted no new frame. ${SCRCPY_VIDEO_BIT_RATE_NETWORK_HINT} Current videoBitRate: ${this.options.videoBitRate} bps (${currentBitRateMbps} Mbps).\nError: ${causeMessage}`);
+                this.lastTransportBacklogWarningAt = now;
+            }
+            estimateFrameTiming(packetPtsUs, receivedAtUs) {
+                const calibration = this.deviceClockCalibration;
+                if (void 0 === packetPtsUs || !calibration) return {
+                    capturedAt: Date.now()
+                };
+                const estimatedAgeUs = this.estimateFrameAgeUs(packetPtsUs, receivedAtUs) ?? 0n;
+                const estimatedAgeMs = Number(estimatedAgeUs) / 1000;
+                const receivedAtWallTimeMs = calibration.hostWallTimeMs + Number(receivedAtUs - calibration.hostMonotonicUs) / 1000;
+                return {
+                    capturedAt: receivedAtWallTimeMs - estimatedAgeMs,
+                    estimatedAgeMs
+                };
+            }
+            clearFrameCache() {
+                this.lastRawKeyframe = null;
+                this.lastRawKeyframeAt = 0;
+                this.lastRawKeyframePtsUs = void 0;
+                this.lastRawKeyframeEstimatedAgeMs = void 0;
+            }
+            monotonicTimeUs() {
+                return process.hrtime.bigint() / 1000n;
+            }
+            resetFrameFreshnessState() {
+                this.frameFreshnessBarrierPtsUs = null;
+                this.frameFreshnessBarrierReason = null;
+                this.frameFreshnessBarrierPending = false;
+                this.frameFreshnessBarrierGeneration = 0;
+                this.deviceClockCalibration = null;
+                this.lastFramePtsUs = null;
+                this.frameFreshnessError = null;
+                this.lastFrameFreshnessWarningAt = 0;
+            }
             subscribeKeyframes(listener) {
                 this.keyframeListeners.add(listener);
                 this.resetIdleTimer();
@@ -281,10 +463,17 @@ var __webpack_modules__ = {
                 };
             }
             getLatestRawKeyframe() {
+                const frame = this.getCachedKeyframeCandidate();
+                if (!frame || !this.isFrameAgeAcceptable(frame.ptsUs)) return null;
+                return frame;
+            }
+            getCachedKeyframeCandidate() {
                 if (!this.lastRawKeyframe || !this.spsHeader) return null;
                 return {
                     data: this.lastRawKeyframe,
                     header: this.spsHeader,
+                    ptsUs: this.lastRawKeyframePtsUs,
+                    estimatedAgeMs: this.lastRawKeyframeEstimatedAgeMs,
                     capturedAt: this.lastRawKeyframeAt
                 };
             }
@@ -294,55 +483,94 @@ var __webpack_modules__ = {
                     frame.data
                 ]));
             }
+            async waitForUsableKeyframe(timeoutMs) {
+                const deadline = Date.now() + timeoutMs;
+                let candidate = this.getCachedKeyframeCandidate();
+                while(true){
+                    if (candidate && this.isFrameAgeAcceptable(candidate.ptsUs)) return candidate;
+                    const remainingMs = deadline - Date.now();
+                    if (remainingMs <= 0) throw new Error(`No fresh keyframe received within ${timeoutMs}ms`);
+                    candidate = await this.waitForNextKeyframe(remainingMs);
+                }
+            }
+            async prepareFreshFrame() {
+                await this.ensureConnected();
+                await this.ensureFrameClockCalibration();
+                await this.waitForKeyframe();
+                await this.waitForUsableKeyframe(MAX_KEYFRAME_WAIT_MS);
+            }
+            async waitForPlanningFrame() {
+                let planningBarrierArmed = false;
+                let deadline = Date.now() + FRESH_FRAME_TIMEOUT_MS;
+                let candidate = this.getCachedKeyframeCandidate();
+                while(true){
+                    if (candidate) {
+                        if (void 0 === candidate.ptsUs) throw new Error('Scrcpy frame has no PTS metadata; cannot prove planning freshness');
+                        const ageUs = this.estimateFrameAgeUs(candidate.ptsUs);
+                        if (null === ageUs) throw new Error('Scrcpy frame clock is not calibrated; cannot prove planning freshness');
+                        if (ageUs <= MAX_FRAME_AGE_US) return candidate;
+                        if (planningBarrierArmed) this.clearFrameCache();
+                        else {
+                            debugScrcpy(`Planning candidate PTS ${candidate.ptsUs}µs has absolute age ${Number(ageUs) / 1000}ms, exceeding the ${Number(MAX_FRAME_AGE_US / 1000n)}ms limit; arming a planning freshness barrier`);
+                            await this.setFreshnessBarrier('stale planning frame');
+                            planningBarrierArmed = true;
+                            deadline = Date.now() + FRESH_FRAME_TIMEOUT_MS;
+                        }
+                    }
+                    const remainingMs = deadline - Date.now();
+                    if (remainingMs <= 0) throw new Error(`No scrcpy frame crossed the active freshness target within ${FRESH_FRAME_TIMEOUT_MS}ms`);
+                    candidate = await this.waitForNextKeyframe(remainingMs);
+                }
+            }
+            async closeStaleStreamAndCreateFallbackError(error) {
+                this.warnTransportBacklog(error);
+                const causeMessage = error instanceof Error ? error.message : String(error);
+                await this.disconnect();
+                return new ScrcpyFreshFrameUnavailableError(`Unable to obtain a fresh scrcpy frame; the stale stream epoch was closed so the caller can use ADB screenshot fallback. ${causeMessage}`, {
+                    cause: error
+                });
+            }
             async getScreenshotJpeg() {
                 const perfStart = Date.now();
                 const t1 = Date.now();
                 await this.ensureConnected();
                 const connectTime = Date.now() - t1;
                 const t2 = Date.now();
-                await this.waitForKeyframe();
-                const spsWaitTime = Date.now() - t2;
-                const t3 = Date.now();
-                let keyframeBuffer;
-                let frameSource;
+                let frame;
                 try {
-                    keyframeBuffer = await this.waitForNextKeyframe(FRESH_FRAME_TIMEOUT_MS);
-                    frameSource = 'fresh';
-                } catch  {
-                    if (this.lastRawKeyframe && this.spsHeader) {
-                        keyframeBuffer = Buffer.concat([
-                            this.spsHeader,
-                            this.lastRawKeyframe
-                        ]);
-                        frameSource = 'cached';
-                    } else {
-                        keyframeBuffer = await this.waitForNextKeyframe(MAX_KEYFRAME_WAIT_MS);
-                        frameSource = 'fresh-retry';
-                    }
+                    await this.ensureFrameClockCalibration();
+                    await this.waitForKeyframe();
+                    frame = await this.waitForPlanningFrame();
+                } catch (error) {
+                    throw await this.closeStaleStreamAndCreateFallbackError(error);
                 }
-                const frameWaitTime = Date.now() - t3;
+                const frameWaitTime = Date.now() - t2;
+                const keyframeBuffer = Buffer.concat([
+                    frame.header,
+                    frame.data
+                ]);
                 this.resetIdleTimer();
-                debugScrcpy(`Decoding H.264 stream: ${keyframeBuffer.length} bytes (${frameSource})`);
-                const t4 = Date.now();
+                debugScrcpy(`Decoding H.264 stream: ${keyframeBuffer.length} bytes (post-barrier)`);
+                const t5 = Date.now();
                 const result = await this.decodeH264ToJpeg(keyframeBuffer);
-                const decodeTime = Date.now() - t4;
+                const decodeTime = Date.now() - t5;
                 const totalTime = Date.now() - perfStart;
-                debugScrcpy(`Performance: total=${totalTime}ms (connect=${connectTime}ms, spsWait=${spsWaitTime}ms, frameWait=${frameWaitTime}ms[${frameSource}], decode=${decodeTime}ms)`);
+                debugScrcpy(`Performance: total=${totalTime}ms (connect=${connectTime}ms, frameWait=${frameWaitTime}ms, decode=${decodeTime}ms)`);
                 return result;
             }
             getResolution() {
                 return this.videoResolution;
             }
-            notifyKeyframeWaiters(buf) {
+            notifyKeyframeWaiters(frame) {
                 const resolvers = this.keyframeResolvers;
                 this.keyframeResolvers = [];
-                for (const resolve of resolvers)resolve(buf);
+                for (const resolve of resolvers)resolve(frame);
             }
             waitForNextKeyframe(timeoutMs) {
                 return new Promise((resolve, reject)=>{
-                    const wrappedResolve = (buf)=>{
+                    const wrappedResolve = (frame)=>{
                         clearTimeout(timer);
-                        resolve(buf);
+                        resolve(frame);
                     };
                     const timer = setTimeout(()=>{
                         this.keyframeResolvers = this.keyframeResolvers.filter((r)=>r !== wrappedResolve);
@@ -465,11 +693,11 @@ var __webpack_modules__ = {
                 this.videoStream = null;
                 this.streamReader = null;
                 this.spsHeader = null;
-                this.lastRawKeyframe = null;
-                this.lastRawKeyframeAt = 0;
+                this.clearFrameCache();
                 this.isInitialized = false;
                 this.keyframeResolvers = [];
                 this.keyframeListeners.clear();
+                this.resetFrameFreshnessState();
                 if (reader) try {
                     await reader.cancel();
                 } catch (error) {
@@ -499,8 +727,19 @@ var __webpack_modules__ = {
                 _define_property(this, "keyframeListeners", new Set());
                 _define_property(this, "lastRawKeyframe", null);
                 _define_property(this, "lastRawKeyframeAt", 0);
+                _define_property(this, "lastRawKeyframePtsUs", void 0);
+                _define_property(this, "lastRawKeyframeEstimatedAgeMs", void 0);
                 _define_property(this, "videoResolution", null);
                 _define_property(this, "streamReader", null);
+                _define_property(this, "frameFreshnessBarrierPtsUs", null);
+                _define_property(this, "frameFreshnessBarrierReason", null);
+                _define_property(this, "frameFreshnessBarrierPending", false);
+                _define_property(this, "frameFreshnessBarrierGeneration", 0);
+                _define_property(this, "deviceClockCalibration", null);
+                _define_property(this, "lastFramePtsUs", null);
+                _define_property(this, "frameFreshnessError", null);
+                _define_property(this, "lastFrameFreshnessWarningAt", 0);
+                _define_property(this, "lastTransportBacklogWarningAt", 0);
                 this.adb = adb;
                 const requestedBitRate = options.videoBitRate ?? DEFAULT_VIDEO_BIT_RATE;
                 const clampedBitRate = Math.min(requestedBitRate, MAX_VIDEO_BIT_RATE);
@@ -639,6 +878,7 @@ const DEFAULT_ADB_SERVER_ENDPOINT = {
 class ScrcpyDeviceAdapter {
     isEnabled() {
         if (!this.isConfigured()) return false;
+        if (this.freshnessRecoveryPending || this.recoveryPromise) return false;
         return null === this.retryAfter || Date.now() >= this.retryAfter;
     }
     getStatus() {
@@ -650,12 +890,18 @@ class ScrcpyDeviceAdapter {
         };
     }
     isConfigured() {
-        return this.scrcpyConfig?.enabled ?? scrcpy_manager.o.enabled;
+        return this.scrcpyConfig?.enabled ?? scrcpy_manager.ov.enabled;
     }
     async initialize(deviceInfo) {
+        if (this.recoveryPromise) {
+            await this.recoveryPromise;
+            if (this.manager?.isConnected()) return;
+        }
+        this.freshnessRecoveryPending = false;
         try {
             const manager = await this.ensureManager(deviceInfo);
             await manager.ensureConnected();
+            await this.applyPendingActionBarrier(manager);
             this.clearFailure();
         } catch (error) {
             this.recordFailure(error);
@@ -665,24 +911,27 @@ class ScrcpyDeviceAdapter {
     recordFailure(error) {
         this.lastError = error instanceof Error ? error.message : String(error);
         this.retryAfter = Date.now() + SCRCPY_RETRY_COOLDOWN_MS;
+        this.freshnessRecoveryPending = false;
     }
     clearFailure() {
         this.lastError = null;
         this.retryAfter = null;
+        this.freshnessRecoveryPending = false;
     }
     ensureRetryReady() {
+        if (this.freshnessRecoveryPending || this.recoveryPromise) throw new Error('scrcpy freshness recovery is in progress');
         if (null === this.retryAfter || Date.now() >= this.retryAfter) return;
         throw new Error(`scrcpy retry is cooling down until ${new Date(this.retryAfter).toISOString()}. Last error: ${this.lastError}`);
     }
     resolveConfig(deviceInfo) {
         if (this.resolvedConfig) return this.resolvedConfig;
         const config = this.scrcpyConfig;
-        const maxSize = config?.maxSize ?? scrcpy_manager.o.maxSize;
-        const videoBitRate = config?.videoBitRate ?? scrcpy_manager.o.videoBitRate;
+        const maxSize = config?.maxSize ?? scrcpy_manager.ov.maxSize;
+        const videoBitRate = config?.videoBitRate ?? scrcpy_manager.ov.videoBitRate;
         this.resolvedConfig = {
             enabled: this.isConfigured(),
             maxSize,
-            idleTimeoutMs: config?.idleTimeoutMs ?? scrcpy_manager.o.idleTimeoutMs,
+            idleTimeoutMs: config?.idleTimeoutMs ?? scrcpy_manager.ov.idleTimeoutMs,
             videoBitRate
         };
         return this.resolvedConfig;
@@ -716,24 +965,40 @@ class ScrcpyDeviceAdapter {
     }
     async screenshotBase64(deviceInfo) {
         this.ensureRetryReady();
+        let manager = null;
         try {
-            const manager = await this.ensureManager(deviceInfo);
+            manager = await this.ensureManager(deviceInfo);
+            await manager.ensureConnected();
+            await this.applyPendingActionBarrier(manager);
             const screenshotBuffer = await manager.getScreenshotJpeg();
             this.clearFailure();
             return createImgBase64ByFormat('jpeg', screenshotBuffer.toString('base64'));
         } catch (error) {
+            if ((0, scrcpy_manager.GJ)(error)) {
+                this.markFreshnessRecoveryPending(manager, error);
+                throw error;
+            }
             this.recordFailure(error);
             throw error;
         }
     }
     async subscribeKeyframes(deviceInfo, listener) {
         this.ensureRetryReady();
+        this.keyframeListeners.add(listener);
         try {
             const manager = await this.ensureManager(deviceInfo);
             await manager.ensureConnected();
+            await this.applyPendingActionBarrier(manager);
+            await manager.ensureFrameClockCalibration();
             this.clearFailure();
-            return manager.subscribeKeyframes(listener);
+            this.attachKeyframeListener(manager, listener);
+            return ()=>{
+                this.keyframeListeners.delete(listener);
+                this.keyframeUnsubscribers.get(listener)?.();
+                this.keyframeUnsubscribers.delete(listener);
+            };
         } catch (error) {
+            this.keyframeListeners.delete(listener);
             this.recordFailure(error);
             throw error;
         }
@@ -741,6 +1006,83 @@ class ScrcpyDeviceAdapter {
     getLatestRawKeyframe() {
         return this.manager?.getLatestRawKeyframe() ?? null;
     }
+    attachKeyframeListener(manager, listener) {
+        this.keyframeUnsubscribers.get(listener)?.();
+        this.keyframeUnsubscribers.set(listener, manager.subscribeKeyframes(listener));
+    }
+    attachKeyframeListeners(manager) {
+        this.keyframeUnsubscribers.clear();
+        for (const listener of this.keyframeListeners)this.attachKeyframeListener(manager, listener);
+    }
+    markFreshnessRecoveryPending(manager, error) {
+        this.lastError = error.message;
+        this.retryAfter = null;
+        this.freshnessRecoveryPending = true;
+        this.keyframeUnsubscribers.clear();
+        if (manager && this.manager === manager) this.manager = null;
+    }
+    async applyPendingActionBarrier(manager) {
+        if (!this.pendingActionBarrier) return;
+        await manager.setFreshnessBarrier('completed input action while scrcpy was unavailable');
+        this.pendingActionBarrier = false;
+    }
+    recoverAfterAdbScreenshot(deviceInfo) {
+        if (!this.freshnessRecoveryPending || this.recoveryPromise) return;
+        const generation = this.lifecycleGeneration;
+        const recovery = (async ()=>{
+            let manager = null;
+            try {
+                manager = await this.ensureManager(deviceInfo);
+                await manager.ensureConnected();
+                await this.applyPendingActionBarrier(manager);
+                await manager.prepareFreshFrame();
+                if (generation !== this.lifecycleGeneration) {
+                    await manager.disconnect();
+                    if (this.manager === manager) this.manager = null;
+                    return;
+                }
+                this.attachKeyframeListeners(manager);
+                this.clearFailure();
+                debugAdapter('Scrcpy freshness recovery completed in background');
+            } catch (error) {
+                if (manager) {
+                    await manager.disconnect();
+                    if (this.manager === manager) this.manager = null;
+                }
+                this.freshnessRecoveryPending = false;
+                this.recordFailure(error);
+                debugAdapter(`Scrcpy background freshness recovery failed: ${error}`);
+                throw error;
+            }
+        })();
+        this.recoveryPromise = recovery;
+        recovery.catch(()=>{}).finally(()=>{
+            if (this.recoveryPromise === recovery) this.recoveryPromise = null;
+        });
+    }
+    async markActionBarrier() {
+        const manager = this.manager;
+        if (!manager?.isConnected()) {
+            this.pendingActionBarrier = true;
+            return;
+        }
+        try {
+            await manager.setFreshnessBarrier('completed input action');
+            this.pendingActionBarrier = false;
+            this.clearFailure();
+        } catch (error) {
+            this.pendingActionBarrier = true;
+            this.recordFailure(error);
+            debugAdapter(`Unable to mark scrcpy action barrier; disabling this stream: ${error}`);
+            try {
+                await manager.disconnect();
+            } catch (disconnectError) {
+                debugAdapter(`Error disconnecting scrcpy after barrier failure: ${disconnectError}`);
+            } finally{
+                if (this.manager === manager) this.manager = null;
+            }
+        }
+    }
     async decodeRawKeyframeToJpegBase64(frame) {
         if (!this.manager) throw new Error('scrcpy manager is not initialized');
         const jpegBuffer = await this.manager.decodeRawKeyframeToJpeg(frame);
@@ -764,6 +1106,13 @@ class ScrcpyDeviceAdapter {
         return resolution.width / physicalWidth;
     }
     async disconnect() {
+        this.lifecycleGeneration += 1;
+        this.freshnessRecoveryPending = false;
+        this.pendingActionBarrier = false;
+        for (const unsubscribe of this.keyframeUnsubscribers.values())unsubscribe();
+        this.keyframeUnsubscribers.clear();
+        this.keyframeListeners.clear();
+        if (this.recoveryPromise) await this.recoveryPromise.catch(()=>{});
         if (this.manager) {
             try {
                 await this.manager.disconnect();
@@ -783,6 +1132,12 @@ class ScrcpyDeviceAdapter {
         _define_property(this, "resolvedConfig", void 0);
         _define_property(this, "lastError", void 0);
         _define_property(this, "retryAfter", void 0);
+        _define_property(this, "freshnessRecoveryPending", void 0);
+        _define_property(this, "recoveryPromise", void 0);
+        _define_property(this, "lifecycleGeneration", void 0);
+        _define_property(this, "pendingActionBarrier", void 0);
+        _define_property(this, "keyframeListeners", void 0);
+        _define_property(this, "keyframeUnsubscribers", void 0);
         this.deviceId = deviceId;
         this.scrcpyConfig = scrcpyConfig;
         this.resolveAdbServerEndpoint = resolveAdbServerEndpoint;
@@ -790,6 +1145,12 @@ class ScrcpyDeviceAdapter {
         this.resolvedConfig = null;
         this.lastError = null;
         this.retryAfter = null;
+        this.freshnessRecoveryPending = false;
+        this.recoveryPromise = null;
+        this.lifecycleGeneration = 0;
+        this.pendingActionBarrier = false;
+        this.keyframeListeners = new Set();
+        this.keyframeUnsubscribers = new Map();
     }
 }
 const TAG_RE = /<(\/?)([A-Za-z_][A-Za-z0-9_.\-:]*)([^>]*?)(\/?)>/g;
@@ -1016,6 +1377,20 @@ async function captureAndroidUITree(options) {
     }
     throw new Error(`Unable to capture Android UI tree after ${failures.length} attempt(s): ${failures.join('; ')}`);
 }
+function createVisualActionRegistry(definitions, onActionSettled) {
+    const registeredActions = {};
+    for (const actionName of Object.keys(definitions)){
+        const dispatch = definitions[actionName];
+        registeredActions[actionName] = async (...args)=>{
+            try {
+                return await dispatch(...args);
+            } finally{
+                await onActionSettled(actionName);
+            }
+        };
+    }
+    return registeredActions;
+}
 function device_define_property(obj, key, value) {
     if (key in obj) Object.defineProperty(obj, key, {
         value: value,
@@ -1116,19 +1491,12 @@ class AndroidDevice {
                     }
                 },
                 call: async (param)=>{
-                    const element = param.locate;
-                    const startPoint = element ? {
-                        left: element.center[0],
-                        top: element.center[1]
-                    } : void 0;
                     if (!param || !param.direction) throw new Error('PullGesture requires a direction parameter');
-                    if ('down' === param.direction) await this.pullDown(startPoint, param.distance, param.duration);
-                    else if ('up' === param.direction) await this.pullUp(startPoint, param.distance, param.duration);
-                    else throw new Error(`Unknown pull direction: ${param.direction}`);
+                    await this.visualActions.pullGesture(param);
                 }
             })
         ];
-        const platformActions = createPlatformActions(this);
+        const platformActions = createPlatformActions(this.visualActions);
         let platformSpecificActions = Object.values(platformActions);
         if (this.options?.exposeRunAdbShellAction === false) platformSpecificActions = platformSpecificActions.filter((action)=>action !== platformActions.RunAdbShell);
         const customActions = this.customActions || [];
@@ -1138,6 +1506,16 @@ class AndroidDevice {
             ...customActions
         ];
     }
+    async performPullGesture(param) {
+        const element = param.locate;
+        const startPoint = element ? {
+            left: element.center[0],
+            top: element.center[1]
+        } : void 0;
+        if ('down' === param.direction) await this.pullDownRaw(startPoint, param.distance, param.duration);
+        else if ('up' === param.direction) await this.pullUpRaw(startPoint, param.distance, param.duration);
+        else throw new Error(`Unknown pull direction: ${param.direction}`);
+    }
     async performActionScroll(param) {
         const element = param.locate;
         const startingPoint = element ? {
@@ -1145,20 +1523,32 @@ class AndroidDevice {
             top: element.center[1]
         } : void 0;
         const scrollToEventName = param?.scrollType;
-        if ('scrollToTop' === scrollToEventName) await this.scrollUntilTop(startingPoint);
-        else if ('scrollToBottom' === scrollToEventName) await this.scrollUntilBottom(startingPoint);
-        else if ('scrollToRight' === scrollToEventName) await this.scrollUntilRight(startingPoint);
-        else if ('scrollToLeft' === scrollToEventName) await this.scrollUntilLeft(startingPoint);
+        if ('scrollToTop' === scrollToEventName) await this.scrollUntilTopRaw(startingPoint);
+        else if ('scrollToBottom' === scrollToEventName) await this.scrollUntilBottomRaw(startingPoint);
+        else if ('scrollToRight' === scrollToEventName) await this.scrollUntilRightRaw(startingPoint);
+        else if ('scrollToLeft' === scrollToEventName) await this.scrollUntilLeftRaw(startingPoint);
         else if ('singleAction' !== scrollToEventName && scrollToEventName) throw new Error(`Unknown scroll event type: ${scrollToEventName}, param: ${JSON.stringify(param)}`);
         else {
-            if (param?.direction !== 'down' && param && param.direction) if ('up' === param.direction) await this.scrollUp(param.distance || void 0, startingPoint);
-            else if ('left' === param.direction) await this.scrollLeft(param.distance || void 0, startingPoint);
-            else if ('right' === param.direction) await this.scrollRight(param.distance || void 0, startingPoint);
+            if (param?.direction !== 'down' && param && param.direction) if ('up' === param.direction) await this.scrollUpRaw(param.distance || void 0, startingPoint);
+            else if ('left' === param.direction) await this.scrollLeftRaw(param.distance || void 0, startingPoint);
+            else if ('right' === param.direction) await this.scrollRightRaw(param.distance || void 0, startingPoint);
             else throw new Error(`Unknown scroll direction: ${param.direction}`);
-            else await this.scrollDown(param?.distance || void 0, startingPoint);
+            else await this.scrollDownRaw(param?.distance || void 0, startingPoint);
             await sleep(500);
         }
     }
+    async runAdbShellRaw(param, context) {
+        const adb = await this.getAdb();
+        const stdout = await runAdbShellStdoutOrThrow(adb, param.command, void 0 === param.timeout ? void 0 : {
+            timeout: param.timeout
+        });
+        const planningFeedback = buildRunAdbShellPlanningFeedback({
+            command: param.command,
+            stdout
+        });
+        if (planningFeedback && context?.task) context.task.planningFeedback = planningFeedback;
+        return stdout;
+    }
     describe() {
         return this.description || `DeviceId: ${this.deviceId}`;
     }
@@ -1255,15 +1645,15 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         const adapter = this.getScrcpyAdapter();
         if (!adapter.isEnabled()) throw new Error('scrcpy is not available for frame observation');
         const deviceInfo = await this.getDevicePhysicalInfo();
-        let latest = adapter.getLatestRawKeyframe();
-        const unsubscribe = await adapter.subscribeKeyframes(deviceInfo, (frame)=>{
-            latest = frame;
-        });
+        const unsubscribe = await adapter.subscribeKeyframes(deviceInfo, ()=>{});
         return {
-            latest: ()=>latest ? {
+            latest: ()=>{
+                const latest = adapter.getLatestRawKeyframe();
+                return latest ? {
                     ref: latest,
                     capturedAt: latest.capturedAt
-                } : null,
+                } : null;
+            },
             decode: async (refs)=>{
                 const images = [];
                 for (const frameRef of refs)images.push(await adapter.decodeRawKeyframeToJpegBase64(frameRef.ref));
@@ -1297,6 +1687,9 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         return this.appNameMapping[normalizedAppName];
     }
     async launch(uri) {
+        return this.visualActions.launch(uri);
+    }
+    async launchRaw(uri) {
         const adb = await this.getAdb();
         this.uri = uri;
         try {
@@ -1322,6 +1715,9 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         return this;
     }
     async terminate(uri) {
+        await this.visualActions.terminate(uri);
+    }
+    async terminateRaw(uri) {
         const packagePart = uri.includes('/') ? uri.split('/')[0] : uri;
         const resolved = this.resolvePackageName(packagePart) ?? packagePart;
         const adb = await this.getAdb();
@@ -1337,6 +1733,9 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         }
     }
     async execYadb(keyboardContent) {
+        await this.visualActions.execYadb(keyboardContent);
+    }
+    async execYadbRaw(keyboardContent) {
         this.warnYadbOnNonDefaultDisplay('keyboard input');
         await this.ensureYadb();
         const adb = await this.getAdb();
@@ -1593,14 +1992,15 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
     async screenshotBase64() {
         debugDevice('screenshotBase64 begin');
         const adapter = this.getScrcpyAdapter();
+        let scrcpyDeviceInfo = null;
         if (adapter.isEnabled()) try {
             debugDevice('Attempting scrcpy screenshot...');
-            const deviceInfo = await this.getDevicePhysicalInfo();
-            const result = await adapter.screenshotBase64(deviceInfo);
+            scrcpyDeviceInfo = await this.getDevicePhysicalInfo();
+            const result = await adapter.screenshotBase64(scrcpyDeviceInfo);
             debugDevice('screenshotBase64 end (scrcpy mode)');
             return result;
         } catch (error) {
-            warnDevice(`Scrcpy screenshot failed, falling back to standard ADB method.\nError: ${error}`);
+            warnDevice(`Scrcpy screenshot failed, falling back to standard ADB method. This may be caused by transport backlog. ${scrcpy_manager.Xr}\nError: ${error}`);
         }
         const adb = await this.getAdb();
         let screenshotBuffer;
@@ -1678,9 +2078,13 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
             });
         }
         debugDevice('screenshotBase64 end');
+        if (scrcpyDeviceInfo) adapter.recoverAfterAdbScreenshot(scrcpyDeviceInfo);
         return result;
     }
     async clearInput(element) {
+        await this.visualActions.clearInput(element);
+    }
+    async clearInputRaw(element) {
         if (element) await this.tapPoint({
             x: element.center[0],
             y: element.center[1]
@@ -1714,6 +2118,9 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         return '';
     }
     async scrollUntilTop(startPoint) {
+        await this.visualActions.scrollUntilTop(startPoint);
+    }
+    async scrollUntilTopRaw(startPoint) {
         if (startPoint) {
             const { height } = await this.size();
             const start = {
@@ -1728,10 +2135,13 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
             await sleep(1000);
             return;
         }
-        await repeat(defaultScrollUntilTimes, ()=>this.scroll(0, -9999999, defaultFastScrollDuration));
+        await repeat(defaultScrollUntilTimes, ()=>this.scrollRaw(0, -9999999, defaultFastScrollDuration));
         await sleep(1000);
     }
     async scrollUntilBottom(startPoint) {
+        await this.visualActions.scrollUntilBottom(startPoint);
+    }
+    async scrollUntilBottomRaw(startPoint) {
         if (startPoint) {
             const start = {
                 x: Math.round(startPoint.left),
@@ -1745,10 +2155,13 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
             await sleep(1000);
             return;
         }
-        await repeat(defaultScrollUntilTimes, ()=>this.scroll(0, 9999999, defaultFastScrollDuration));
+        await repeat(defaultScrollUntilTimes, ()=>this.scrollRaw(0, 9999999, defaultFastScrollDuration));
         await sleep(1000);
     }
     async scrollUntilLeft(startPoint) {
+        await this.visualActions.scrollUntilLeft(startPoint);
+    }
+    async scrollUntilLeftRaw(startPoint) {
         if (startPoint) {
             const { width } = await this.size();
             const start = {
@@ -1763,10 +2176,13 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
             await sleep(1000);
             return;
         }
-        await repeat(defaultScrollUntilTimes, ()=>this.scroll(-9999999, 0, defaultFastScrollDuration));
+        await repeat(defaultScrollUntilTimes, ()=>this.scrollRaw(-9999999, 0, defaultFastScrollDuration));
         await sleep(1000);
     }
     async scrollUntilRight(startPoint) {
+        await this.visualActions.scrollUntilRight(startPoint);
+    }
+    async scrollUntilRightRaw(startPoint) {
         if (startPoint) {
             const start = {
                 x: Math.round(startPoint.left),
@@ -1780,10 +2196,13 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
             await sleep(1000);
             return;
         }
-        await repeat(defaultScrollUntilTimes, ()=>this.scroll(9999999, 0, defaultFastScrollDuration));
+        await repeat(defaultScrollUntilTimes, ()=>this.scrollRaw(9999999, 0, defaultFastScrollDuration));
         await sleep(1000);
     }
     async scrollUp(distance, startPoint) {
+        await this.visualActions.scrollUp(distance, startPoint);
+    }
+    async scrollUpRaw(distance, startPoint) {
         const { height } = await this.size();
         const scrollDistance = Math.round(distance || height);
         const hasExplicitDistance = void 0 !== distance;
@@ -1797,9 +2216,12 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
             await this.dragPoint(start, end);
             return;
         }
-        await this.scroll(0, -scrollDistance, void 0, hasExplicitDistance, 'up');
+        await this.scrollRaw(0, -scrollDistance, void 0, hasExplicitDistance, 'up');
     }
     async scrollDown(distance, startPoint) {
+        await this.visualActions.scrollDown(distance, startPoint);
+    }
+    async scrollDownRaw(distance, startPoint) {
         const { height } = await this.size();
         const scrollDistance = Math.round(distance || height);
         const hasExplicitDistance = void 0 !== distance;
@@ -1813,9 +2235,12 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
             await this.dragPoint(start, end);
             return;
         }
-        await this.scroll(0, scrollDistance, void 0, hasExplicitDistance, 'down');
+        await this.scrollRaw(0, scrollDistance, void 0, hasExplicitDistance, 'down');
     }
     async scrollLeft(distance, startPoint) {
+        await this.visualActions.scrollLeft(distance, startPoint);
+    }
+    async scrollLeftRaw(distance, startPoint) {
         const { width } = await this.size();
         const scrollDistance = Math.round(distance || width);
         const hasExplicitDistance = void 0 !== distance;
@@ -1829,9 +2254,12 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
             await this.dragPoint(start, end);
             return;
         }
-        await this.scroll(-scrollDistance, 0, void 0, hasExplicitDistance, 'left');
+        await this.scrollRaw(-scrollDistance, 0, void 0, hasExplicitDistance, 'left');
     }
     async scrollRight(distance, startPoint) {
+        await this.visualActions.scrollRight(distance, startPoint);
+    }
+    async scrollRightRaw(distance, startPoint) {
         const { width } = await this.size();
         const scrollDistance = Math.round(distance || width);
         const hasExplicitDistance = void 0 !== distance;
@@ -1845,7 +2273,7 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
             await this.dragPoint(start, end);
             return;
         }
-        await this.scroll(scrollDistance, 0, void 0, hasExplicitDistance, 'right');
+        await this.scrollRaw(scrollDistance, 0, void 0, hasExplicitDistance, 'right');
     }
     async ensureYadb() {
         if (!this.yadbPushed) {
@@ -1874,11 +2302,11 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
             const reason = IME_STRATEGY === IME_STRATEGY_ALWAYS_YADB ? "imeStrategy 'always-yadb' requires yadb" : 'text contains characters that require yadb (non-ASCII, format specifiers, or mixed quotes)';
             throw new Error(`${reason}, but yadb (app_process) cannot target non-default displayId=${this.options?.displayId}. Use displayId=0 or a different imeStrategy.`);
         }
-        if (needsYadb) await this.execYadb(escapeForShell(text));
+        if (needsYadb) await this.execYadbRaw(escapeForShell(text));
         else await this.shellInputText(text, {
             keyboardTypeDelay: typeDelay
         });
-        if (true === shouldAutoDismissKeyboard) await this.hideKeyboard(options);
+        if (true === shouldAutoDismissKeyboard) await this.hideKeyboardRaw(options);
     }
     normalizeKeyName(key) {
         const keyMap = {
@@ -1948,6 +2376,9 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         await adb.shell(`input${this.getDisplayArg()} swipe ${fromX} ${fromY} ${toX} ${toY} ${duration}`);
     }
     async scroll(deltaX, deltaY, duration, warnOnClamp = false, direction) {
+        await this.visualActions.scroll(deltaX, deltaY, duration, warnOnClamp, direction);
+    }
+    async scrollRaw(deltaX, deltaY, duration, warnOnClamp = false, direction) {
         if (0 === deltaX && 0 === deltaY) throw new Error('Scroll distance cannot be zero in both directions');
         const { width, height } = await this.size();
         const n = 4;
@@ -2012,12 +2443,21 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         }
     }
     async back() {
+        await this.visualActions.back();
+    }
+    async backRaw() {
         await this.shellInputKeyevent(4);
     }
     async home() {
+        await this.visualActions.home();
+    }
+    async homeRaw() {
         await this.shellInputKeyevent(3);
     }
     async recentApps() {
+        await this.visualActions.recentApps();
+    }
+    async recentAppsRaw() {
         await this.shellInputKeyevent(187);
     }
     async longPressPoint(point, duration = 2000) {
@@ -2026,6 +2466,9 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         await adb.shell(`input${this.getDisplayArg()} swipe ${adjustedX} ${adjustedY} ${adjustedX} ${adjustedY} ${duration}`);
     }
     async pullDown(startPoint, distance, duration = 800) {
+        await this.visualActions.pullDown(startPoint, distance, duration);
+    }
+    async pullDownRaw(startPoint, distance, duration = 800) {
         const { width, height } = await this.size();
         const start = startPoint ? {
             x: Math.round(startPoint.left),
@@ -2039,13 +2482,19 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
             x: start.x,
             y: start.y + pullDistance
         };
-        await this.pullDrag(start, end, duration);
+        await this.pullDragRaw(start, end, duration);
         await sleep(200);
     }
     async pullDrag(from, to, duration) {
+        await this.visualActions.pullDrag(from, to, duration);
+    }
+    async pullDragRaw(from, to, duration) {
         await this.swipePoint(from, to, duration);
     }
     async pullUp(startPoint, distance, duration = 600) {
+        await this.visualActions.pullUp(startPoint, distance, duration);
+    }
+    async pullUpRaw(startPoint, distance, duration = 600) {
         const { width, height } = await this.size();
         const start = startPoint ? {
             x: Math.round(startPoint.left),
@@ -2059,7 +2508,7 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
             x: start.x,
             y: start.y - pullDistance
         };
-        await this.pullDrag(start, end, duration);
+        await this.pullDragRaw(start, end, duration);
         await sleep(100);
     }
     getDisplayArg() {
@@ -2122,6 +2571,9 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         }
     }
     async hideKeyboard(options, timeoutMs = 1000) {
+        return this.visualActions.hideKeyboard(options, timeoutMs);
+    }
+    async hideKeyboardRaw(options, timeoutMs = 1000) {
         const adb = await this.getAdb();
         const keyboardDismissStrategy = options?.keyboardDismissStrategy ?? this.options?.keyboardDismissStrategy ?? 'esc-first';
         const keyboardStatus = await adb.isSoftKeyboardPresent();
@@ -2176,55 +2628,91 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         device_define_property(this, "interfaceType", 'android');
         device_define_property(this, "uri", void 0);
         device_define_property(this, "options", void 0);
+        device_define_property(this, "visualActions", createVisualActionRegistry({
+            tap: (point)=>this.tapPoint(point),
+            doubleClick: (point)=>this.doubleTapPoint(point),
+            longPress: (point, opts)=>this.longPressPoint(point, opts?.duration),
+            dragAndDrop: (from, to)=>this.dragPoint(from, to),
+            keyboardPress: (keyName)=>this.pressKey(keyName),
+            typeText: async (value, opts)=>{
+                const target = opts?.target;
+                if (target && opts?.replace !== false) await this.clearInputRaw(target);
+                else if (target) await this.tapPoint({
+                    x: target.center[0],
+                    y: target.center[1]
+                });
+                if (opts?.focusOnly) return;
+                await this.typeText(value, opts);
+            },
+            clearInput: (target)=>this.clearInputRaw(target),
+            cursorMove: async (direction, times = 1)=>{
+                const arrowKey = 'left' === direction ? 'ArrowLeft' : 'ArrowRight';
+                for(let index = 0; index < times; index++)await this.pressKey(arrowKey);
+            },
+            swipe: async (start, end, opts)=>{
+                const duration = opts?.duration ?? 300;
+                const repeatCount = opts?.repeat ?? 1;
+                for(let index = 0; index < repeatCount; index++)await this.dragPoint(start, end, duration);
+            },
+            pinch: async (center, opts)=>{
+                if ('number' == typeof this.options?.displayId && 0 !== this.options.displayId) throw new Error(`Pinch is not supported on a non-default display (displayId=${this.options.displayId}). The underlying yadb tool only injects gestures into the default display.`);
+                const { x: adjCenterX, y: adjCenterY } = await this.adjustCoordinates(Math.round(center.x), Math.round(center.y));
+                const ratio = 0 !== adjCenterX && 0 !== center.x ? adjCenterX / center.x : 1;
+                const adjStartDist = Math.round(opts.startDistance * ratio);
+                const adjEndDist = Math.round(opts.endDistance * ratio);
+                await this.ensureYadb();
+                const adb = await this.getAdb();
+                await adb.shell(`app_process -Djava.class.path=/data/local/tmp/yadb /data/local/tmp com.ysbing.yadb.Main -pinch ${adjCenterX} ${adjCenterY} ${adjStartDist} ${adjEndDist} ${opts.duration}`);
+            },
+            actionScroll: (param)=>this.performActionScroll(param),
+            back: ()=>this.backRaw(),
+            home: ()=>this.homeRaw(),
+            recentApps: ()=>this.recentAppsRaw(),
+            pullGesture: (param)=>this.performPullGesture(param),
+            launch: (uri)=>this.launchRaw(uri),
+            terminate: (uri)=>this.terminateRaw(uri),
+            runAdbShell: (param, context)=>this.runAdbShellRaw(param, context),
+            execYadb: (keyboardContent)=>this.execYadbRaw(keyboardContent),
+            scrollUntilTop: (startPoint)=>this.scrollUntilTopRaw(startPoint),
+            scrollUntilBottom: (startPoint)=>this.scrollUntilBottomRaw(startPoint),
+            scrollUntilLeft: (startPoint)=>this.scrollUntilLeftRaw(startPoint),
+            scrollUntilRight: (startPoint)=>this.scrollUntilRightRaw(startPoint),
+            scrollUp: (distance, startPoint)=>this.scrollUpRaw(distance, startPoint),
+            scrollDown: (distance, startPoint)=>this.scrollDownRaw(distance, startPoint),
+            scrollLeft: (distance, startPoint)=>this.scrollLeftRaw(distance, startPoint),
+            scrollRight: (distance, startPoint)=>this.scrollRightRaw(distance, startPoint),
+            scroll: (deltaX, deltaY, duration, warnOnClamp, direction)=>this.scrollRaw(deltaX, deltaY, duration, warnOnClamp, direction),
+            pullDown: (startPoint, distance, duration)=>this.pullDownRaw(startPoint, distance, duration),
+            pullDrag: (from, to, duration)=>this.pullDragRaw(from, to, duration),
+            pullUp: (startPoint, distance, duration)=>this.pullUpRaw(startPoint, distance, duration),
+            hideKeyboard: (options, timeoutMs)=>this.hideKeyboardRaw(options, timeoutMs)
+        }, async ()=>{
+            await this.scrcpyAdapter?.markActionBarrier();
+        }));
         device_define_property(this, "inputPrimitives", {
             pointer: {
-                tap: (point)=>this.tapPoint(point),
-                doubleClick: (point)=>this.doubleTapPoint(point),
-                longPress: (point, opts)=>this.longPressPoint(point, opts?.duration),
-                dragAndDrop: (from, to)=>this.dragPoint(from, to)
+                tap: this.visualActions.tap,
+                doubleClick: this.visualActions.doubleClick,
+                longPress: this.visualActions.longPress,
+                dragAndDrop: this.visualActions.dragAndDrop
             },
             keyboard: {
-                keyboardPress: (keyName)=>this.pressKey(keyName),
-                typeText: async (value, opts)=>{
-                    const target = opts?.target;
-                    if (target && opts?.replace !== false) await this.clearInput(target);
-                    else if (target) await this.tapPoint({
-                        x: target.center[0],
-                        y: target.center[1]
-                    });
-                    if (opts?.focusOnly) return;
-                    await this.typeText(value, opts);
-                },
-                clearInput: (target)=>this.clearInput(target),
-                cursorMove: async (direction, times = 1)=>{
-                    const arrowKey = 'left' === direction ? 'ArrowLeft' : 'ArrowRight';
-                    for(let i = 0; i < times; i++)await this.pressKey(arrowKey);
-                }
+                keyboardPress: this.visualActions.keyboardPress,
+                typeText: this.visualActions.typeText,
+                clearInput: this.visualActions.clearInput,
+                cursorMove: this.visualActions.cursorMove
             },
             touch: {
-                swipe: async (start, end, opts)=>{
-                    const duration = opts?.duration ?? 300;
-                    const repeatCount = opts?.repeat ?? 1;
-                    for(let i = 0; i < repeatCount; i++)await this.dragPoint(start, end, duration);
-                },
-                pinch: async (center, opts)=>{
-                    if ('number' == typeof this.options?.displayId && 0 !== this.options.displayId) throw new Error(`Pinch is not supported on a non-default display (displayId=${this.options.displayId}). The underlying yadb tool only injects gestures into the default display.`);
-                    const { x: adjCenterX, y: adjCenterY } = await this.adjustCoordinates(Math.round(center.x), Math.round(center.y));
-                    const ratio = 0 !== adjCenterX && 0 !== center.x ? adjCenterX / center.x : 1;
-                    const adjStartDist = Math.round(opts.startDistance * ratio);
-                    const adjEndDist = Math.round(opts.endDistance * ratio);
-                    await this.ensureYadb();
-                    const adb = await this.getAdb();
-                    await adb.shell(`app_process -Djava.class.path=/data/local/tmp/yadb /data/local/tmp com.ysbing.yadb.Main -pinch ${adjCenterX} ${adjCenterY} ${adjStartDist} ${adjEndDist} ${opts.duration}`);
-                }
+                swipe: this.visualActions.swipe,
+                pinch: this.visualActions.pinch
             },
             scroll: {
-                scroll: (param)=>this.performActionScroll(param)
+                scroll: this.visualActions.actionScroll
             },
             system: {
-                backButton: ()=>this.back(),
-                homeButton: ()=>this.home(),
-                recentAppsButton: ()=>this.recentApps()
+                backButton: this.visualActions.back,
+                homeButton: this.visualActions.home,
+                recentAppsButton: this.visualActions.recentApps
             }
         });
         node_assert(deviceId, 'deviceId is required for AndroidDevice');
@@ -2246,7 +2734,7 @@ const launchParamSchema = z.object({
 const terminateParamSchema = z.object({
     uri: z.string().describe('Package name or app name to terminate. Use the exact package name, e.g. com.android.settings.')
 });
-const createPlatformActions = (device)=>({
+const createPlatformActions = (visualActions)=>({
         RunAdbShell: defineAction({
             name: 'RunAdbShell',
             description: 'Execute an ADB shell command on the Android device and return the command stdout. Read the returned stdout to decide the next step; the stdout may indicate either success or failure.',
@@ -2257,16 +2745,7 @@ const createPlatformActions = (device)=>({
             },
             call: async (param, context)=>{
                 if (!param.command || '' === param.command.trim()) throw new Error('RunAdbShell requires a non-empty command parameter');
-                const adb = await device.getAdb();
-                const stdout = await runAdbShellStdoutOrThrow(adb, param.command, void 0 === param.timeout ? void 0 : {
-                    timeout: param.timeout
-                });
-                const planningFeedback = buildRunAdbShellPlanningFeedback({
-                    command: param.command,
-                    stdout
-                });
-                if (planningFeedback && context?.task) context.task.planningFeedback = planningFeedback;
-                return stdout;
+                return visualActions.runAdbShell(param, context);
             }
         }),
         Launch: defineAction({
@@ -2279,7 +2758,7 @@ const createPlatformActions = (device)=>({
             },
             call: async (param)=>{
                 if (!param.uri || '' === param.uri.trim()) throw new Error('Launch requires a non-empty uri parameter');
-                await device.launch(param.uri);
+                await visualActions.launch(param.uri);
             }
         }),
         Terminate: defineAction({
@@ -2289,7 +2768,7 @@ const createPlatformActions = (device)=>({
             paramSchema: terminateParamSchema,
             call: async (param)=>{
                 if (!param.uri || '' === param.uri.trim()) throw new Error('Terminate requires a non-empty uri parameter');
-                await device.terminate(param.uri);
+                await visualActions.terminate(param.uri);
             }
         })
     });