@midscene/android 1.10.9 → 1.10.10-beta-20260805080137.0

package/dist/lib/index.js

@@ -5,8 +5,10 @@ const __rslib_import_meta_url__ = /*#__PURE__*/ function() {
 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");
@@ -42,6 +44,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;
@@ -52,6 +62,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;
         }
@@ -234,24 +262,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) {
@@ -261,6 +290,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();
@@ -270,10 +452,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
                 };
             }
@@ -283,55 +472,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);
@@ -454,11 +682,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) {
@@ -488,8 +716,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);
@@ -672,6 +911,7 @@ ${stdout ? truncateAdbShellStream(stdout, 'stdout') : EMPTY_ADB_SHELL_STDOUT}`;
     class ScrcpyDeviceAdapter {
         isEnabled() {
             if (!this.isConfigured()) return false;
+            if (this.freshnessRecoveryPending || this.recoveryPromise) return false;
             return null === this.retryAfter || Date.now() >= this.retryAfter;
         }
         getStatus() {
@@ -683,12 +923,18 @@ ${stdout ? truncateAdbShellStream(stdout, 'stdout') : EMPTY_ADB_SHELL_STDOUT}`;
             };
         }
         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);
@@ -698,24 +944,27 @@ ${stdout ? truncateAdbShellStream(stdout, 'stdout') : EMPTY_ADB_SHELL_STDOUT}`;
         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;
@@ -749,24 +998,40 @@ ${stdout ? truncateAdbShellStream(stdout, 'stdout') : EMPTY_ADB_SHELL_STDOUT}`;
         }
         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 (0, img_namespaceObject.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;
             }
@@ -774,6 +1039,83 @@ ${stdout ? truncateAdbShellStream(stdout, 'stdout') : EMPTY_ADB_SHELL_STDOUT}`;
         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);
@@ -797,6 +1139,13 @@ ${stdout ? truncateAdbShellStream(stdout, 'stdout') : EMPTY_ADB_SHELL_STDOUT}`;
             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();
@@ -816,6 +1165,12 @@ ${stdout ? truncateAdbShellStream(stdout, 'stdout') : EMPTY_ADB_SHELL_STDOUT}`;
             _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;
@@ -823,6 +1178,12 @@ ${stdout ? truncateAdbShellStream(stdout, 'stdout') : EMPTY_ADB_SHELL_STDOUT}`;
             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;
@@ -1049,6 +1410,20 @@ ${stdout ? truncateAdbShellStream(stdout, 'stdout') : EMPTY_ADB_SHELL_STDOUT}`;
         }
         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,
@@ -1149,19 +1524,12 @@ ${stdout ? truncateAdbShellStream(stdout, 'stdout') : EMPTY_ADB_SHELL_STDOUT}`;
                         }
                     },
                     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 || [];
@@ -1171,6 +1539,16 @@ ${stdout ? truncateAdbShellStream(stdout, 'stdout') : EMPTY_ADB_SHELL_STDOUT}`;
                 ...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 ? {
@@ -1178,20 +1556,32 @@ ${stdout ? truncateAdbShellStream(stdout, 'stdout') : EMPTY_ADB_SHELL_STDOUT}`;
                 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 (0, utils_namespaceObject.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}`;
         }
@@ -1288,15 +1678,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));
@@ -1330,6 +1720,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 {
@@ -1355,6 +1748,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();
@@ -1370,6 +1766,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();
@@ -1626,14 +2025,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;
@@ -1711,9 +2111,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]
@@ -1747,6 +2151,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 = {
@@ -1761,10 +2168,13 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
                 await (0, utils_namespaceObject.sleep)(1000);
                 return;
             }
-            await (0, shared_utils_namespaceObject.repeat)(defaultScrollUntilTimes, ()=>this.scroll(0, -9999999, defaultFastScrollDuration));
+            await (0, shared_utils_namespaceObject.repeat)(defaultScrollUntilTimes, ()=>this.scrollRaw(0, -9999999, defaultFastScrollDuration));
             await (0, utils_namespaceObject.sleep)(1000);
         }
         async scrollUntilBottom(startPoint) {
+            await this.visualActions.scrollUntilBottom(startPoint);
+        }
+        async scrollUntilBottomRaw(startPoint) {
             if (startPoint) {
                 const start = {
                     x: Math.round(startPoint.left),
@@ -1778,10 +2188,13 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
                 await (0, utils_namespaceObject.sleep)(1000);
                 return;
             }
-            await (0, shared_utils_namespaceObject.repeat)(defaultScrollUntilTimes, ()=>this.scroll(0, 9999999, defaultFastScrollDuration));
+            await (0, shared_utils_namespaceObject.repeat)(defaultScrollUntilTimes, ()=>this.scrollRaw(0, 9999999, defaultFastScrollDuration));
             await (0, utils_namespaceObject.sleep)(1000);
         }
         async scrollUntilLeft(startPoint) {
+            await this.visualActions.scrollUntilLeft(startPoint);
+        }
+        async scrollUntilLeftRaw(startPoint) {
             if (startPoint) {
                 const { width } = await this.size();
                 const start = {
@@ -1796,10 +2209,13 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
                 await (0, utils_namespaceObject.sleep)(1000);
                 return;
             }
-            await (0, shared_utils_namespaceObject.repeat)(defaultScrollUntilTimes, ()=>this.scroll(-9999999, 0, defaultFastScrollDuration));
+            await (0, shared_utils_namespaceObject.repeat)(defaultScrollUntilTimes, ()=>this.scrollRaw(-9999999, 0, defaultFastScrollDuration));
             await (0, utils_namespaceObject.sleep)(1000);
         }
         async scrollUntilRight(startPoint) {
+            await this.visualActions.scrollUntilRight(startPoint);
+        }
+        async scrollUntilRightRaw(startPoint) {
             if (startPoint) {
                 const start = {
                     x: Math.round(startPoint.left),
@@ -1813,10 +2229,13 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
                 await (0, utils_namespaceObject.sleep)(1000);
                 return;
             }
-            await (0, shared_utils_namespaceObject.repeat)(defaultScrollUntilTimes, ()=>this.scroll(9999999, 0, defaultFastScrollDuration));
+            await (0, shared_utils_namespaceObject.repeat)(defaultScrollUntilTimes, ()=>this.scrollRaw(9999999, 0, defaultFastScrollDuration));
             await (0, utils_namespaceObject.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;
@@ -1830,9 +2249,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;
@@ -1846,9 +2268,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;
@@ -1862,9 +2287,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;
@@ -1878,7 +2306,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) {
@@ -1907,11 +2335,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 = {
@@ -1981,6 +2409,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;
@@ -2045,12 +2476,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) {
@@ -2059,6 +2499,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),
@@ -2072,13 +2515,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 (0, utils_namespaceObject.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),
@@ -2092,7 +2541,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 (0, utils_namespaceObject.sleep)(100);
         }
         getDisplayArg() {
@@ -2155,6 +2604,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();
@@ -2209,55 +2661,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
                 }
             });
             external_node_assert_default()(deviceId, 'deviceId is required for AndroidDevice');
@@ -2279,7 +2767,7 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
     const terminateParamSchema = core_namespaceObject.z.object({
         uri: core_namespaceObject.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: (0, device_namespaceObject.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.',
@@ -2290,16 +2778,7 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
                 },
                 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: (0, device_namespaceObject.defineAction)({
@@ -2312,7 +2791,7 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
                 },
                 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: (0, device_namespaceObject.defineAction)({
@@ -2322,7 +2801,7 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
                 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);
                 }
             })
         });