@midscene/android 1.12.0 → 1.12.1-beta-20260824081858.0

package/dist/types/index.d.ts

@@ -336,6 +336,7 @@ export declare class AndroidDevice implements AbstractInterface {
 
 declare type AndroidInitArgs = AgentBehaviorInitArgs & {
     deviceId?: string;
+    scrcpyVideoBitRate?: number;
     useScrcpy?: boolean;
 };
 
@@ -425,13 +426,15 @@ export declare class ScrcpyDeviceAdapter {
     private scrcpyConfig;
     private resolveAdbServerEndpoint;
     private manager;
+    private managerPromise;
     private resolvedConfig;
     private lastError;
     private retryAfter;
     private freshnessRecoveryPending;
+    private freshnessRestartPromise;
     private recoveryPromise;
     private lifecycleGeneration;
-    private pendingActionBarrier;
+    private pendingActionBarrierAtHostUs;
     private keyframeListeners;
     private keyframeUnsubscribers;
     constructor(deviceId: string, scrcpyConfig: ScrcpyConfig | undefined, resolveAdbServerEndpoint?: ResolveAdbServerEndpoint);
@@ -451,7 +454,15 @@ export declare class ScrcpyDeviceAdapter {
      * receives the highest quality image for AI processing.
      * videoBitRate uses the shared default unless explicitly configured.
      */
-    resolveConfig(deviceInfo: DevicePhysicalInfo): ResolvedScrcpyConfig;
+    resolveConfig(_deviceInfo?: DevicePhysicalInfo): ResolvedScrcpyConfig;
+    /**
+     * Apply the configured scrcpy video bound to an independently captured
+     * fallback screenshot. This prevents planning and report images from returning
+     * to full device resolution while the scrcpy stream is temporarily unavailable.
+     * The bound only applies when scrcpy is configured as enabled; disabling
+     * scrcpy preserves the existing ADB/yadb screenshot behavior.
+     */
+    prepareFallbackScreenshot(screenshotBase64: string): Promise<string>;
     /**
      * Get or create the ScrcpyScreenshotManager.
      * Uses dynamic import for @yume-chan packages (ESM-only, must use await import in CJS builds).
@@ -459,9 +470,14 @@ export declare class ScrcpyDeviceAdapter {
     ensureManager(deviceInfo: DevicePhysicalInfo): Promise<ScrcpyScreenshotManager>;
     /**
      * Take a screenshot via scrcpy, returns base64 string.
-     * Throws on failure (caller should fallback to ADB).
+     * A stale established stream is restarted once so a static screen can use
+     * the new epoch's baseline frame. Throws only when that retry also fails, so
+     * the caller can fall back to ADB.
      */
     screenshotBase64(deviceInfo: DevicePhysicalInfo): Promise<string>;
+    private restartAndCaptureOnce;
+    private jpegBufferToBase64;
+    private warnFreshnessFallback;
     /**
      * Subscribe to raw keyframes from the scrcpy stream (ensures the stream is
      * connected first). Frames are raw H.264 — no decoding cost. While
@@ -475,6 +491,8 @@ export declare class ScrcpyDeviceAdapter {
     private attachKeyframeListeners;
     private markFreshnessRecoveryPending;
     private applyPendingActionBarrier;
+    private monotonicTimeUs;
+    private deferActionBarrier;
     /**
      * Start a new scrcpy epoch only after the independent ADB screenshot has
      * completed, so stream startup does not compete with the fallback capture.
@@ -511,13 +529,19 @@ export declare class ScrcpyDeviceAdapter {
     disconnect(): Promise<void>;
 }
 
+declare interface ScrcpyFreshnessBarrierOptions {
+    hostMonotonicUs?: bigint;
+    allowOverAgeForNextCapture?: boolean;
+}
+
 declare class ScrcpyScreenshotManager {
     private adb;
     private scrcpyClient;
     private videoStream;
     private spsHeader;
     private idleTimer;
-    private isConnecting;
+    private connectionPromise;
+    private disposed;
     private isInitialized;
     private options;
     private ffmpegAvailable;
@@ -531,6 +555,9 @@ declare class ScrcpyScreenshotManager {
     private streamReader;
     private frameFreshnessBarrierPtsUs;
     private frameFreshnessBarrierReason;
+    private frameFreshnessBarrierAllowsOverAgeForNextCapture;
+    private streamBaselineFramePending;
+    private streamBaselineFrameDeadlineAt;
     private frameFreshnessBarrierPending;
     private frameFreshnessBarrierGeneration;
     private deviceClockCalibration;
@@ -550,6 +577,7 @@ declare class ScrcpyScreenshotManager {
      * Ensure scrcpy connection is active
      */
     ensureConnected(): Promise<void>;
+    private connectScrcpy;
     private createScrcpyOptions;
     private collectServerOutput;
     private createConnectionError;
@@ -592,10 +620,14 @@ declare class ScrcpyScreenshotManager {
     /**
      * Invalidate cached frames and require future packets to be captured after
      * the host-monotonic action/planning boundary projected onto the device
-     * clock. The projection reuses the single calibration for this stream epoch
-     * and does not issue another ADB clock read.
-     */
-    setFreshnessBarrier(reason: string): Promise<bigint>;
+     * clock. A caller recovering an unavailable stream can pass the original
+     * action-boundary timestamp so connection startup latency does not move the
+     * barrier forward. Action barriers may allow the first proven post-boundary
+     * frame to survive a long wait-after-action delay. The projection reuses the
+     * single calibration for this stream epoch and does not issue another ADB
+     * clock read.
+     */
+    setFreshnessBarrier(reason: string, options?: ScrcpyFreshnessBarrierOptions): Promise<bigint>;
     private isFrameFresh;
     private estimateFrameAgeUs;
     private estimateFrameAge;
@@ -603,9 +635,11 @@ declare class ScrcpyScreenshotManager {
     private getCalibrationUncertaintyUs;
     private isFrameAgeAcceptable;
     private warnFrameFreshness;
+    private transportBacklogMessage;
     private warnTransportBacklog;
     private estimateFrameTiming;
     private clearFrameCache;
+    private restoreFrameCache;
     private monotonicTimeUs;
     private resetFrameFreshnessState;
     /**
@@ -620,6 +654,9 @@ declare class ScrcpyScreenshotManager {
     /** Latest raw keyframe seen on the stream, or null if none yet. */
     getLatestRawKeyframe(): RawKeyframe | null;
     private getCachedKeyframeCandidate;
+    private canReuseFrameAcrossActionWait;
+    private canUseStreamBaseline;
+    private consumeActionFreshnessBarrier;
     /**
      * Decode a raw keyframe (from {@link subscribeKeyframes} or
      * {@link getLatestRawKeyframe}) to a JPEG buffer. This is the deferred,
@@ -627,20 +664,24 @@ 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.
+     * Ensure a newly connected stream has a calibrated, usable epoch baseline
+     * or a frame that crossed its active action barrier before exposing it again
+     * after ADB fallback.
      */
     prepareFreshFrame(): Promise<void>;
     private waitForPlanningFrame;
     private closeStaleStreamAndCreateFallbackError;
     /**
      * Get screenshot as JPEG.
-     * 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.
+     * A newly connected stream may use its first epoch-local frame once during
+     * the bounded startup window, because a static screen will not emit another
+     * frame after clock calibration completes.
+     * Reuses one frame that crossed the active input-action barrier even if a
+     * long wait-after-action made its absolute age exceed the planning limit.
+     * Other over-age candidates arm 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>;
     /**
@@ -687,6 +728,11 @@ declare class ScrcpyScreenshotManager {
      * Disconnect scrcpy
      */
     disconnect(): Promise<void>;
+    /**
+     * Permanently release the scrcpy stream and the owned yume ADB transport.
+     * Unlike disconnect(), a disposed manager cannot be reconnected.
+     */
+    dispose(): Promise<void>;
     /**
      * Check if scrcpy is initialized and connected
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@midscene/android",
-  "version": "1.12.0",
+  "version": "1.12.1-beta-20260824081858.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/web-infra-dev/midscene.git",
@@ -34,15 +34,15 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@yume-chan/adb": "2.5.1",
+    "@yume-chan/adb": "2.6.3",
     "@yume-chan/adb-scrcpy": "2.3.2",
     "@yume-chan/adb-server-node-tcp": "2.5.2",
     "@yume-chan/scrcpy": "2.3.0",
-    "@yume-chan/stream-extra": "2.1.0",
+    "@yume-chan/stream-extra": "2.6.1",
     "appium-adb": "12.12.1",
     "sharp": "^0.34.3",
-    "@midscene/core": "1.12.0",
-    "@midscene/shared": "1.12.0"
+    "@midscene/core": "1.12.1-beta-20260824081858.0",
+    "@midscene/shared": "1.12.1-beta-20260824081858.0"
   },
   "optionalDependencies": {
     "@ffmpeg-installer/ffmpeg": "^1.1.0"
@@ -56,7 +56,7 @@
     "typescript": "^5.8.3",
     "undici": "^6.0.0",
     "zod": "^3.25.1",
-    "@midscene/playground": "1.12.0"
+    "@midscene/playground": "1.12.1-beta-20260824081858.0"
   },
   "license": "MIT",
   "scripts": {