@midscene/android 1.10.9 → 1.10.10-beta-20260805080137.0

package/dist/types/index.d.ts

@@ -111,9 +111,12 @@ export declare class AndroidDevice implements AbstractInterface {
     interfaceType: InterfaceType;
     uri: string | undefined;
     options?: AndroidDeviceOpt;
+    private readonly visualActions;
     readonly inputPrimitives: MobileInputPrimitives;
     actionSpace(): DeviceAction<any>[];
+    private performPullGesture;
     private performActionScroll;
+    private runAdbShellRaw;
     constructor(deviceId: string, options?: AndroidDeviceOpt);
     describe(): string;
     connect(): Promise<ADB>;
@@ -158,13 +161,16 @@ export declare class AndroidDevice implements AbstractInterface {
      */
     private resolvePackageName;
     launch(uri: string): Promise<AndroidDevice>;
+    private launchRaw;
     /**
      * Terminate (force-stop) an Android app by package name.
      * Supports app name resolution via setAppNameMapping.
      * If uri contains "/" (e.g. com.example.app/.MainActivity), only the package part is used.
      */
     terminate(uri: string): Promise<void>;
+    private terminateRaw;
     execYadb(keyboardContent: string): Promise<void>;
+    private execYadbRaw;
     getElementsInfo(): Promise<ElementInfo[]>;
     getElementsNodeTree(): Promise<any>;
     getUITree(): Promise<UITreeSnapshot>;
@@ -211,16 +217,25 @@ export declare class AndroidDevice implements AbstractInterface {
     private warnScrollDistanceClamped;
     screenshotBase64(): Promise<string>;
     clearInput(element?: ElementInfo): Promise<void>;
+    private clearInputRaw;
     forceScreenshot(path: string): Promise<void>;
     url(): Promise<string>;
     scrollUntilTop(startPoint?: Point): Promise<void>;
+    private scrollUntilTopRaw;
     scrollUntilBottom(startPoint?: Point): Promise<void>;
+    private scrollUntilBottomRaw;
     scrollUntilLeft(startPoint?: Point): Promise<void>;
+    private scrollUntilLeftRaw;
     scrollUntilRight(startPoint?: Point): Promise<void>;
+    private scrollUntilRightRaw;
     scrollUp(distance?: number, startPoint?: Point): Promise<void>;
+    private scrollUpRaw;
     scrollDown(distance?: number, startPoint?: Point): Promise<void>;
+    private scrollDownRaw;
     scrollLeft(distance?: number, startPoint?: Point): Promise<void>;
+    private scrollLeftRaw;
     scrollRight(distance?: number, startPoint?: Point): Promise<void>;
+    private scrollRightRaw;
     ensureYadb(): Promise<void>;
     /**
      * Check if text contains characters that may cause issues with ADB inputText.
@@ -243,6 +258,7 @@ export declare class AndroidDevice implements AbstractInterface {
     private dragPoint;
     private swipePoint;
     scroll(deltaX: number, deltaY: number, duration?: number, warnOnClamp?: boolean, direction?: ScrollDirection): Promise<void>;
+    private scrollRaw;
     destroy(): Promise<void>;
     /**
      * Get the current device-local time as a formatted string.
@@ -251,10 +267,14 @@ export declare class AndroidDevice implements AbstractInterface {
      */
     getDeviceLocalTimeString(format?: string): Promise<string>;
     back(): Promise<void>;
+    private backRaw;
     home(): Promise<void>;
+    private homeRaw;
     recentApps(): Promise<void>;
+    private recentAppsRaw;
     private longPressPoint;
     pullDown(startPoint?: Point, distance?: number, duration?: number): Promise<void>;
+    private pullDownRaw;
     pullDrag(from: {
         x: number;
         y: number;
@@ -262,7 +282,9 @@ export declare class AndroidDevice implements AbstractInterface {
         x: number;
         y: number;
     }, duration: number): Promise<void>;
+    private pullDragRaw;
     pullUp(startPoint?: Point, distance?: number, duration?: number): Promise<void>;
+    private pullUpRaw;
     private getDisplayArg;
     /**
      * Send one or more Android keyevent codes via `input -d <id> keyevent`.
@@ -292,6 +314,7 @@ export declare class AndroidDevice implements AbstractInterface {
     getPhysicalDisplayId(): Promise<string | null>;
     private resolvePhysicalDisplayId;
     hideKeyboard(options?: AndroidDeviceInputOpt, timeoutMs?: number): Promise<boolean>;
+    private hideKeyboardRaw;
 }
 
 declare type AndroidInitArgs = AgentBehaviorInitArgs & {
@@ -346,6 +369,10 @@ declare interface RawKeyframe {
     data: Buffer;
     /** SPS/PPS header active when this frame was produced (needed to decode). */
     header: Buffer;
+    /** Device-monotonic capture timestamp forwarded by scrcpy. */
+    ptsUs?: bigint;
+    /** Estimated frame age when the packet reached the host. */
+    estimatedAgeMs?: number;
     capturedAt: number;
 }
 
@@ -384,6 +411,12 @@ export declare class ScrcpyDeviceAdapter {
     private resolvedConfig;
     private lastError;
     private retryAfter;
+    private freshnessRecoveryPending;
+    private recoveryPromise;
+    private lifecycleGeneration;
+    private pendingActionBarrier;
+    private keyframeListeners;
+    private keyframeUnsubscribers;
     constructor(deviceId: string, scrcpyConfig: ScrcpyConfig | undefined, resolveAdbServerEndpoint?: ResolveAdbServerEndpoint);
     isEnabled(): boolean;
     getStatus(): ScrcpyStatus;
@@ -421,6 +454,21 @@ export declare class ScrcpyDeviceAdapter {
     subscribeKeyframes(deviceInfo: DevicePhysicalInfo, listener: (frame: RawKeyframe) => void): Promise<() => void>;
     /** Latest raw keyframe seen on the stream, or null if none yet. */
     getLatestRawKeyframe(): RawKeyframe | null;
+    private attachKeyframeListener;
+    private attachKeyframeListeners;
+    private markFreshnessRecoveryPending;
+    private applyPendingActionBarrier;
+    /**
+     * Start a new scrcpy epoch only after the independent ADB screenshot has
+     * completed, so stream startup does not compete with the fallback capture.
+     */
+    recoverAfterAdbScreenshot(deviceInfo: DevicePhysicalInfo): void;
+    /**
+     * Move the scrcpy PTS barrier past a completed input action. Barrier failures
+     * must not turn a successfully injected action into an action error; disable
+     * the stream and let subsequent captures use the existing ADB fallback.
+     */
+    markActionBarrier(): Promise<void>;
     /**
      * Decode a raw keyframe to a JPEG data URL. Deferred, per-frame-expensive
      * step (one ffmpeg process per call) — only call on sampled frames.
@@ -460,8 +508,19 @@ declare class ScrcpyScreenshotManager {
     private keyframeListeners;
     private lastRawKeyframe;
     private lastRawKeyframeAt;
+    private lastRawKeyframePtsUs;
+    private lastRawKeyframeEstimatedAgeMs;
     private videoResolution;
     private streamReader;
+    private frameFreshnessBarrierPtsUs;
+    private frameFreshnessBarrierReason;
+    private frameFreshnessBarrierPending;
+    private frameFreshnessBarrierGeneration;
+    private deviceClockCalibration;
+    private lastFramePtsUs;
+    private frameFreshnessError;
+    private lastFrameFreshnessWarningAt;
+    private lastTransportBacklogWarningAt;
     constructor(adb: Adb, options?: ScrcpyScreenshotOptions);
     /**
      * Validate environment prerequisites (ffmpeg, scrcpy-server, etc.)
@@ -505,6 +564,28 @@ declare class ScrcpyScreenshotManager {
      * at high resolutions where raw chunks may not align with frame boundaries.
      */
     private processFrame;
+    /**
+     * Read the Android uptime clock used by Surface/MediaCodec frame PTS values.
+     * The host timestamps bracket the ADB request so frame age can also be
+     * estimated on the host wall clock for reports.
+     */
+    private readDeviceClockCalibration;
+    ensureFrameClockCalibration(): Promise<void>;
+    /**
+     * Invalidate cached frames and require future packets to be captured after a
+     * newly sampled point on the device clock after a completed input or
+     * platform action.
+     */
+    setFreshnessBarrier(reason: string): Promise<bigint>;
+    private isFrameFresh;
+    private estimateFrameAgeUs;
+    private isFrameAgeAcceptable;
+    private warnFrameFreshness;
+    private warnTransportBacklog;
+    private estimateFrameTiming;
+    private clearFrameCache;
+    private monotonicTimeUs;
+    private resetFrameFreshnessState;
     /**
      * Subscribe to raw keyframes as they arrive from the stream. While at least
      * one subscriber is active, incoming keyframes keep resetting the idle timer
@@ -516,6 +597,7 @@ declare class ScrcpyScreenshotManager {
     subscribeKeyframes(listener: (frame: RawKeyframe) => void): () => void;
     /** Latest raw keyframe seen on the stream, or null if none yet. */
     getLatestRawKeyframe(): RawKeyframe | null;
+    private getCachedKeyframeCandidate;
     /**
      * Decode a raw keyframe (from {@link subscribeKeyframes} or
      * {@link getLatestRawKeyframe}) to a JPEG buffer. This is the deferred,
@@ -523,10 +605,20 @@ declare class ScrcpyScreenshotManager {
      * sampled frames, never inside a capture loop.
      */
     decodeRawKeyframeToJpeg(frame: RawKeyframe): Promise<Buffer>;
+    private waitForUsableKeyframe;
+    /**
+     * Ensure a newly connected stream has a calibrated, temporally fresh frame
+     * before it is exposed again after ADB fallback.
+     */
+    prepareFreshFrame(): Promise<void>;
+    private waitForPlanningFrame;
+    private closeStaleStreamAndCreateFallbackError;
     /**
      * Get screenshot as JPEG.
-     * Tries to get a fresh frame within a short timeout. If the screen is static
-     * (no new frames arrive), falls back to the latest cached keyframe.
+     * Reuses a frame only when it crossed the active action barrier and its
+     * absolute age is within the accepted limit. An over-age candidate arms a
+     * planning barrier on demand. If no frame crosses the resulting freshness
+     * target in time, close this stream epoch and let the caller use ADB.
      */
     getScreenshotJpeg(): Promise<Buffer>;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@midscene/android",
-  "version": "1.10.9",
+  "version": "1.10.10-beta-20260805080137.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/web-infra-dev/midscene.git",
@@ -41,8 +41,8 @@
     "@yume-chan/stream-extra": "2.1.0",
     "appium-adb": "12.12.1",
     "sharp": "^0.34.3",
-    "@midscene/core": "1.10.9",
-    "@midscene/shared": "1.10.9"
+    "@midscene/core": "1.10.10-beta-20260805080137.0",
+    "@midscene/shared": "1.10.10-beta-20260805080137.0"
   },
   "optionalDependencies": {
     "@ffmpeg-installer/ffmpeg": "^1.1.0"
@@ -56,7 +56,7 @@
     "undici": "^6.0.0",
     "vitest": "3.0.5",
     "zod": "^3.25.1",
-    "@midscene/playground": "1.10.9"
+    "@midscene/playground": "1.10.10-beta-20260805080137.0"
   },
   "license": "MIT",
   "scripts": {