@midscene/computer 1.12.4 → 1.12.5-beta-20260907080441.0

package/dist/es/cli.mjs

@@ -523,8 +523,10 @@ async function captureScreenshot(options) {
 }
 const SMOOTH_MOVE_STEPS_TAP = 8;
 const SMOOTH_MOVE_STEPS_MOUSE_MOVE = 10;
+const SMOOTH_MOVE_STEPS_DRAG = 20;
 const SMOOTH_MOVE_DELAY_TAP = 8;
 const SMOOTH_MOVE_DELAY_MOUSE_MOVE = 10;
+const SMOOTH_MOVE_DELAY_DRAG = 10;
 const MOUSE_MOVE_EFFECT_WAIT = 300;
 const CLICK_SETTLE_DELAY = 50;
 const CLICK_HOLD_DURATION = 100;
@@ -1151,7 +1153,7 @@ Available Displays: ${displays.length > 0 ? displays.map((d)=>d.name).join(', ')
     }
     async healthCheck(displays) {
         console.log('[HealthCheck] Starting health check...');
-        console.log("[HealthCheck] @midscene/computer v1.12.4");
+        console.log("[HealthCheck] @midscene/computer v1.12.5-beta-20260907080441.0");
         console.log('[HealthCheck] Taking screenshot...');
         const screenshotTimeout = 15000;
         let timeoutId;
@@ -1628,7 +1630,10 @@ $g.Dispose(); $bmp.Dispose(); $ms.Dispose()
                     await this.moveDisplayPointer(from, 'Mouse did not reach the drag start target');
                     await this.inputDriver.withMouseButton('left', async ()=>{
                         await this.inputDriver.delay(100);
-                        await this.moveDisplayPointer(to, 'Mouse did not reach the drag end target');
+                        await this.moveDisplayPointer(to, 'Mouse did not reach the drag end target', {
+                            smoothSteps: SMOOTH_MOVE_STEPS_DRAG,
+                            smoothDelay: SMOOTH_MOVE_DELAY_DRAG
+                        });
                         await this.inputDriver.delay(100);
                     });
                 }
@@ -2067,10 +2072,10 @@ function rdp_device_define_property(obj, key, value) {
 const device_debug = getDebug('rdp:device');
 const device_SMOOTH_MOVE_STEPS_TAP = 8;
 const device_SMOOTH_MOVE_STEPS_MOUSE_MOVE = 10;
-const SMOOTH_MOVE_STEPS_DRAG = 12;
+const device_SMOOTH_MOVE_STEPS_DRAG = 12;
 const device_SMOOTH_MOVE_DELAY_TAP = 8;
 const device_SMOOTH_MOVE_DELAY_MOUSE_MOVE = 10;
-const SMOOTH_MOVE_DELAY_DRAG = 10;
+const device_SMOOTH_MOVE_DELAY_DRAG = 10;
 const device_MOUSE_MOVE_EFFECT_WAIT = 300;
 const device_CLICK_HOLD_DURATION = 50;
 const DRAG_HOLD_DURATION = 100;
@@ -2273,8 +2278,8 @@ class RDPDevice {
                     await this.backend.mouseButton('left', 'down');
                     await sleep(DRAG_HOLD_DURATION);
                     await this.movePointer(Math.round(to.x), Math.round(to.y), {
-                        steps: SMOOTH_MOVE_STEPS_DRAG,
-                        stepDelayMs: SMOOTH_MOVE_DELAY_DRAG
+                        steps: device_SMOOTH_MOVE_STEPS_DRAG,
+                        stepDelayMs: device_SMOOTH_MOVE_DELAY_DRAG
                     });
                     await sleep(DRAG_HOLD_DURATION);
                     await this.backend.mouseButton('left', 'up');
@@ -2601,7 +2606,7 @@ const tools = new ComputerMidsceneTools({
 });
 runToolsCLI(tools, 'midscene-computer', {
     stripPrefix: 'computer_',
-    version: "1.12.4",
+    version: "1.12.5-beta-20260907080441.0",
     extraCommands: createReportCliCommands()
 }).catch((e)=>{
     process.exit(reportCLIError(e));

package/dist/es/index.mjs

@@ -523,8 +523,10 @@ async function captureScreenshot(options) {
 }
 const SMOOTH_MOVE_STEPS_TAP = 8;
 const SMOOTH_MOVE_STEPS_MOUSE_MOVE = 10;
+const SMOOTH_MOVE_STEPS_DRAG = 20;
 const SMOOTH_MOVE_DELAY_TAP = 8;
 const SMOOTH_MOVE_DELAY_MOUSE_MOVE = 10;
+const SMOOTH_MOVE_DELAY_DRAG = 10;
 const MOUSE_MOVE_EFFECT_WAIT = 300;
 const CLICK_SETTLE_DELAY = 50;
 const CLICK_HOLD_DURATION = 100;
@@ -1151,7 +1153,7 @@ Available Displays: ${displays.length > 0 ? displays.map((d)=>d.name).join(', ')
     }
     async healthCheck(displays) {
         console.log('[HealthCheck] Starting health check...');
-        console.log("[HealthCheck] @midscene/computer v1.12.4");
+        console.log("[HealthCheck] @midscene/computer v1.12.5-beta-20260907080441.0");
         console.log('[HealthCheck] Taking screenshot...');
         const screenshotTimeout = 15000;
         let timeoutId;
@@ -1628,7 +1630,10 @@ $g.Dispose(); $bmp.Dispose(); $ms.Dispose()
                     await this.moveDisplayPointer(from, 'Mouse did not reach the drag start target');
                     await this.inputDriver.withMouseButton('left', async ()=>{
                         await this.inputDriver.delay(100);
-                        await this.moveDisplayPointer(to, 'Mouse did not reach the drag end target');
+                        await this.moveDisplayPointer(to, 'Mouse did not reach the drag end target', {
+                            smoothSteps: SMOOTH_MOVE_STEPS_DRAG,
+                            smoothDelay: SMOOTH_MOVE_DELAY_DRAG
+                        });
                         await this.inputDriver.delay(100);
                     });
                 }
@@ -2110,10 +2115,10 @@ function rdp_device_define_property(obj, key, value) {
 const device_debug = getDebug('rdp:device');
 const device_SMOOTH_MOVE_STEPS_TAP = 8;
 const device_SMOOTH_MOVE_STEPS_MOUSE_MOVE = 10;
-const SMOOTH_MOVE_STEPS_DRAG = 12;
+const device_SMOOTH_MOVE_STEPS_DRAG = 12;
 const device_SMOOTH_MOVE_DELAY_TAP = 8;
 const device_SMOOTH_MOVE_DELAY_MOUSE_MOVE = 10;
-const SMOOTH_MOVE_DELAY_DRAG = 10;
+const device_SMOOTH_MOVE_DELAY_DRAG = 10;
 const device_MOUSE_MOVE_EFFECT_WAIT = 300;
 const device_CLICK_HOLD_DURATION = 50;
 const DRAG_HOLD_DURATION = 100;
@@ -2316,8 +2321,8 @@ class RDPDevice {
                     await this.backend.mouseButton('left', 'down');
                     await sleep(DRAG_HOLD_DURATION);
                     await this.movePointer(Math.round(to.x), Math.round(to.y), {
-                        steps: SMOOTH_MOVE_STEPS_DRAG,
-                        stepDelayMs: SMOOTH_MOVE_DELAY_DRAG
+                        steps: device_SMOOTH_MOVE_STEPS_DRAG,
+                        stepDelayMs: device_SMOOTH_MOVE_DELAY_DRAG
                     });
                     await sleep(DRAG_HOLD_DURATION);
                     await this.backend.mouseButton('left', 'up');
@@ -2640,7 +2645,7 @@ class ComputerMidsceneTools extends BaseMidsceneTools {
     }
 }
 function version() {
-    const currentVersion = "1.12.4";
+    const currentVersion = "1.12.5-beta-20260907080441.0";
     console.log(`@midscene/computer v${currentVersion}`);
     return currentVersion;
 }

package/dist/lib/cli.js

@@ -549,8 +549,10 @@ async function captureScreenshot(options) {
 }
 const SMOOTH_MOVE_STEPS_TAP = 8;
 const SMOOTH_MOVE_STEPS_MOUSE_MOVE = 10;
+const SMOOTH_MOVE_STEPS_DRAG = 20;
 const SMOOTH_MOVE_DELAY_TAP = 8;
 const SMOOTH_MOVE_DELAY_MOUSE_MOVE = 10;
+const SMOOTH_MOVE_DELAY_DRAG = 10;
 const MOUSE_MOVE_EFFECT_WAIT = 300;
 const CLICK_SETTLE_DELAY = 50;
 const CLICK_HOLD_DURATION = 100;
@@ -1177,7 +1179,7 @@ Available Displays: ${displays.length > 0 ? displays.map((d)=>d.name).join(', ')
     }
     async healthCheck(displays) {
         console.log('[HealthCheck] Starting health check...');
-        console.log("[HealthCheck] @midscene/computer v1.12.4");
+        console.log("[HealthCheck] @midscene/computer v1.12.5-beta-20260907080441.0");
         console.log('[HealthCheck] Taking screenshot...');
         const screenshotTimeout = 15000;
         let timeoutId;
@@ -1654,7 +1656,10 @@ $g.Dispose(); $bmp.Dispose(); $ms.Dispose()
                     await this.moveDisplayPointer(from, 'Mouse did not reach the drag start target');
                     await this.inputDriver.withMouseButton('left', async ()=>{
                         await this.inputDriver.delay(100);
-                        await this.moveDisplayPointer(to, 'Mouse did not reach the drag end target');
+                        await this.moveDisplayPointer(to, 'Mouse did not reach the drag end target', {
+                            smoothSteps: SMOOTH_MOVE_STEPS_DRAG,
+                            smoothDelay: SMOOTH_MOVE_DELAY_DRAG
+                        });
                         await this.inputDriver.delay(100);
                     });
                 }
@@ -2094,10 +2099,10 @@ function rdp_device_define_property(obj, key, value) {
 const device_debug = (0, logger_namespaceObject.getDebug)('rdp:device');
 const device_SMOOTH_MOVE_STEPS_TAP = 8;
 const device_SMOOTH_MOVE_STEPS_MOUSE_MOVE = 10;
-const SMOOTH_MOVE_STEPS_DRAG = 12;
+const device_SMOOTH_MOVE_STEPS_DRAG = 12;
 const device_SMOOTH_MOVE_DELAY_TAP = 8;
 const device_SMOOTH_MOVE_DELAY_MOUSE_MOVE = 10;
-const SMOOTH_MOVE_DELAY_DRAG = 10;
+const device_SMOOTH_MOVE_DELAY_DRAG = 10;
 const device_MOUSE_MOVE_EFFECT_WAIT = 300;
 const device_CLICK_HOLD_DURATION = 50;
 const DRAG_HOLD_DURATION = 100;
@@ -2300,8 +2305,8 @@ class RDPDevice {
                     await this.backend.mouseButton('left', 'down');
                     await (0, utils_namespaceObject.sleep)(DRAG_HOLD_DURATION);
                     await this.movePointer(Math.round(to.x), Math.round(to.y), {
-                        steps: SMOOTH_MOVE_STEPS_DRAG,
-                        stepDelayMs: SMOOTH_MOVE_DELAY_DRAG
+                        steps: device_SMOOTH_MOVE_STEPS_DRAG,
+                        stepDelayMs: device_SMOOTH_MOVE_DELAY_DRAG
                     });
                     await (0, utils_namespaceObject.sleep)(DRAG_HOLD_DURATION);
                     await this.backend.mouseButton('left', 'up');
@@ -2628,7 +2633,7 @@ const tools = new ComputerMidsceneTools({
 });
 (0, cli_namespaceObject.runToolsCLI)(tools, 'midscene-computer', {
     stripPrefix: 'computer_',
-    version: "1.12.4",
+    version: "1.12.5-beta-20260907080441.0",
     extraCommands: (0, core_namespaceObject.createReportCliCommands)()
 }).catch((e)=>{
     process.exit((0, cli_namespaceObject.reportCLIError)(e));

package/dist/lib/index.js

@@ -575,8 +575,10 @@ async function captureScreenshot(options) {
 }
 const SMOOTH_MOVE_STEPS_TAP = 8;
 const SMOOTH_MOVE_STEPS_MOUSE_MOVE = 10;
+const SMOOTH_MOVE_STEPS_DRAG = 20;
 const SMOOTH_MOVE_DELAY_TAP = 8;
 const SMOOTH_MOVE_DELAY_MOUSE_MOVE = 10;
+const SMOOTH_MOVE_DELAY_DRAG = 10;
 const MOUSE_MOVE_EFFECT_WAIT = 300;
 const CLICK_SETTLE_DELAY = 50;
 const CLICK_HOLD_DURATION = 100;
@@ -1203,7 +1205,7 @@ Available Displays: ${displays.length > 0 ? displays.map((d)=>d.name).join(', ')
     }
     async healthCheck(displays) {
         console.log('[HealthCheck] Starting health check...');
-        console.log("[HealthCheck] @midscene/computer v1.12.4");
+        console.log("[HealthCheck] @midscene/computer v1.12.5-beta-20260907080441.0");
         console.log('[HealthCheck] Taking screenshot...');
         const screenshotTimeout = 15000;
         let timeoutId;
@@ -1680,7 +1682,10 @@ $g.Dispose(); $bmp.Dispose(); $ms.Dispose()
                     await this.moveDisplayPointer(from, 'Mouse did not reach the drag start target');
                     await this.inputDriver.withMouseButton('left', async ()=>{
                         await this.inputDriver.delay(100);
-                        await this.moveDisplayPointer(to, 'Mouse did not reach the drag end target');
+                        await this.moveDisplayPointer(to, 'Mouse did not reach the drag end target', {
+                            smoothSteps: SMOOTH_MOVE_STEPS_DRAG,
+                            smoothDelay: SMOOTH_MOVE_DELAY_DRAG
+                        });
                         await this.inputDriver.delay(100);
                     });
                 }
@@ -2164,10 +2169,10 @@ function rdp_device_define_property(obj, key, value) {
 const device_debug = (0, logger_namespaceObject.getDebug)('rdp:device');
 const device_SMOOTH_MOVE_STEPS_TAP = 8;
 const device_SMOOTH_MOVE_STEPS_MOUSE_MOVE = 10;
-const SMOOTH_MOVE_STEPS_DRAG = 12;
+const device_SMOOTH_MOVE_STEPS_DRAG = 12;
 const device_SMOOTH_MOVE_DELAY_TAP = 8;
 const device_SMOOTH_MOVE_DELAY_MOUSE_MOVE = 10;
-const SMOOTH_MOVE_DELAY_DRAG = 10;
+const device_SMOOTH_MOVE_DELAY_DRAG = 10;
 const device_MOUSE_MOVE_EFFECT_WAIT = 300;
 const device_CLICK_HOLD_DURATION = 50;
 const DRAG_HOLD_DURATION = 100;
@@ -2370,8 +2375,8 @@ class RDPDevice {
                     await this.backend.mouseButton('left', 'down');
                     await (0, utils_namespaceObject.sleep)(DRAG_HOLD_DURATION);
                     await this.movePointer(Math.round(to.x), Math.round(to.y), {
-                        steps: SMOOTH_MOVE_STEPS_DRAG,
-                        stepDelayMs: SMOOTH_MOVE_DELAY_DRAG
+                        steps: device_SMOOTH_MOVE_STEPS_DRAG,
+                        stepDelayMs: device_SMOOTH_MOVE_DELAY_DRAG
                     });
                     await (0, utils_namespaceObject.sleep)(DRAG_HOLD_DURATION);
                     await this.backend.mouseButton('left', 'up');
@@ -2698,7 +2703,7 @@ class ComputerMidsceneTools extends base_tools_namespaceObject.BaseMidsceneTools
 }
 const env_namespaceObject = require("@midscene/shared/env");
 function version() {
-    const currentVersion = "1.12.4";
+    const currentVersion = "1.12.5-beta-20260907080441.0";
     console.log(`@midscene/computer v${currentVersion}`);
     return currentVersion;
 }

package/native/rdp/CMakeLists.txt

@@ -92,6 +92,27 @@ if(BUILD_TESTING)
     NAME rdp-session-policy-test
     COMMAND rdp-session-policy-test
   )
+
+  add_executable(
+    rdp-screenshot-test
+    tests/screenshot_test.cpp
+    src/session.cpp
+  )
+  target_include_directories(
+    rdp-screenshot-test PRIVATE
+    ${CMAKE_CURRENT_SOURCE_DIR}/include
+    ${FREERDP_INCLUDE_DIRS}
+  )
+  target_link_libraries(
+    rdp-screenshot-test PRIVATE
+    ${FREERDP_LIBRARIES}
+    Threads::Threads
+  )
+  if(APPLE)
+    target_compile_definitions(rdp-screenshot-test PRIVATE _DARWIN_C_SOURCE)
+  endif()
+  add_test(NAME rdp-screenshot-test COMMAND rdp-screenshot-test)
+  set_tests_properties(rdp-screenshot-test PROPERTIES TIMEOUT 30)
 endif()
 
 if(APPLE)

package/native/rdp/include/rdp_helper_session.hpp

@@ -1,6 +1,7 @@
 #pragma once
 
 #include <atomic>
+#include <chrono>
 #include <condition_variable>
 #include <cstdint>
 #include <mutex>
@@ -76,7 +77,7 @@ class FreeRdpSessionTransport final : public SessionTransport {
   void HookEndPaint(rdpUpdate* update);
   // Records that at least one paint has reached the local framebuffer and
   // wakes Connect().
-  void MarkFramePainted(std::optional<RawFrame> first_frame = std::nullopt);
+  void MarkFramePainted();
   // Records a framebuffer update even when it is too blank or uniform to count
   // as the first informative frame.
   void MarkFramebufferUpdated();
@@ -90,6 +91,7 @@ class FreeRdpSessionTransport final : public SessionTransport {
 
  private:
   friend struct MidsceneRdpContext;
+  friend struct RdpScreenshotTestPeer;
 
   freerdp* instance_ = nullptr;
   std::thread event_thread_;
@@ -110,8 +112,8 @@ class FreeRdpSessionTransport final : public SessionTransport {
   std::atomic<bool> session_active_{false};
   std::condition_variable frame_cv_;
   std::mutex frame_mutex_;
-  std::optional<RawFrame> first_frame_;
-  bool first_frame_consumed_ = false;
+  // Protected by frame_mutex_; use a monotonic clock for screenshot settling.
+  std::chrono::steady_clock::time_point last_frame_update_{};
   pEndPaint original_end_paint_ = nullptr;
   uint16_t mouse_x_ = 0;
   uint16_t mouse_y_ = 0;

package/native/rdp/src/session.cpp

@@ -68,6 +68,8 @@ using FdSetSocket = int;
 // never paints within this window is treated as blank/locked and fails fast
 // instead of feeding an all-black screenshot to the caller.
 constexpr int kFirstFrameTimeoutMs = 20'000;
+constexpr auto kScreenshotQuietPeriod = std::chrono::milliseconds(300);
+constexpr auto kScreenshotTimeout = std::chrono::seconds(3);
 // The first frame should prove that real desktop pixels reached the primary
 // buffer without requiring a complex wallpaper or fully loaded app content.
 constexpr size_t kMinInformativeColorCount = 128;
@@ -436,11 +438,11 @@ bool HasPendingFramebufferInvalidation(rdpContext* context) {
   return hwnd->ninvalid > 0 && hwnd->invalid && !hwnd->invalid->null;
 }
 
-std::optional<RawFrame> CaptureInformativeFramebuffer(rdpContext* context) {
+bool HasInformativeFramebuffer(rdpContext* context) {
   if (!context || !context->gdi || !context->gdi->primary_buffer ||
       context->gdi->width <= 0 || context->gdi->height <= 0 ||
       context->gdi->stride == 0) {
-    return std::nullopt;
+    return false;
   }
 
   rdpGdi* gdi = context->gdi;
@@ -448,7 +450,7 @@ std::optional<RawFrame> CaptureInformativeFramebuffer(rdpContext* context) {
   const auto height = static_cast<size_t>(gdi->height);
   const auto stride = static_cast<size_t>(gdi->stride);
   if (stride < width * 4) {
-    return std::nullopt;
+    return false;
   }
 
   const BYTE* buffer = gdi->primary_buffer;
@@ -489,16 +491,37 @@ std::optional<RawFrame> CaptureInformativeFramebuffer(rdpContext* context) {
 
   if (colors.size() < kMinInformativeColorCount ||
       non_black_pixels < min_non_black_pixels) {
-    return std::nullopt;
+    return false;
   }
+  return true;
+}
 
-  RawFrame frame;
-  frame.size.width = gdi->width;
-  frame.size.height = gdi->height;
-  frame.stride = stride;
-  const size_t buffer_size = stride * height;
-  frame.bgra.assign(buffer, buffer + buffer_size);
-  return frame;
+// Called under the transport mutex so paints and resizes cannot race the copy.
+// A black image is a retryable transition, not a successful screenshot.
+std::optional<RawFrame> CaptureNonBlackFramebuffer(const rdpGdi& gdi) {
+  if (!gdi.primary_buffer || gdi.width <= 0 || gdi.height <= 0 ||
+      gdi.stride < static_cast<size_t>(gdi.width) * 4) {
+    throw std::runtime_error("Remote framebuffer is empty or invalid");
+  }
+
+  // Ignore alpha and row padding. Uniform non-black screens are valid; the
+  // first-paint color-diversity heuristic does not apply to later screenshots.
+  for (int y = 0; y < gdi.height; ++y) {
+    const BYTE* row = gdi.primary_buffer + static_cast<size_t>(y) * gdi.stride;
+    for (int x = 0; x < gdi.width; ++x) {
+      const BYTE* pixel = row + static_cast<size_t>(x) * 4;
+      if (pixel[0] || pixel[1] || pixel[2]) {
+        RawFrame frame;
+        frame.size.width = gdi.width;
+        frame.size.height = gdi.height;
+        frame.stride = static_cast<size_t>(gdi.stride);
+        const size_t buffer_size = frame.stride * static_cast<size_t>(gdi.height);
+        frame.bgra.assign(gdi.primary_buffer, gdi.primary_buffer + buffer_size);
+        return frame;
+      }
+    }
+  }
+  return std::nullopt;
 }
 
 // EndPaint hook chained onto FreeRDP's update pipeline. FreeRDP invokes this
@@ -516,9 +539,8 @@ BOOL MidsceneEndPaint(rdpContext* context) {
       typed_context->owner->MarkFramebufferUpdated();
       if (already_painted) {
         typed_context->owner->MarkFramePainted();
-      } else if (auto first_frame = CaptureInformativeFramebuffer(context);
-                 first_frame.has_value()) {
-        typed_context->owner->MarkFramePainted(std::move(first_frame));
+      } else if (HasInformativeFramebuffer(context)) {
+        typed_context->owner->MarkFramePainted();
       }
     }
   }
@@ -983,8 +1005,7 @@ ConnectionInfo FreeRdpSessionTransport::Connect(const ConnectionConfig& config)
     framebuffer_updates_.store(0, std::memory_order_relaxed);
     {
       std::lock_guard<std::mutex> frame_lock(frame_mutex_);
-      first_frame_.reset();
-      first_frame_consumed_ = false;
+      last_frame_update_ = {};
     }
     original_end_paint_ = nullptr;
     ClearSessionErrorLocked();
@@ -1083,36 +1104,46 @@ void FreeRdpSessionTransport::Disconnect() {
 }
 
 RawFrame FreeRdpSessionTransport::CaptureFrame() {
-  std::lock_guard<std::mutex> lock(mutex_);
-  if (!connected_ || !instance_ || !instance_->context || !instance_->context->gdi) {
-    throw std::runtime_error("No remote framebuffer is available");
-  }
+  const auto started = std::chrono::steady_clock::now();
+  const auto deadline = started + kScreenshotTimeout;
+  for (;;) {
+    std::unique_lock<std::mutex> lock(mutex_);
+    if (!connected_ || !instance_ || !instance_->context ||
+        !instance_->context->gdi ||
+        !session_active_.load(std::memory_order_relaxed)) {
+      throw std::runtime_error(
+          last_error_ ? "RDP screenshot failed: " + last_error_->message
+                      : "No remote framebuffer is available");
+    }
 
-  if (frames_painted_.load(std::memory_order_relaxed) == 0) {
-    throw std::runtime_error(
-        "Remote framebuffer has not received its first paint yet");
-  }
+    if (frames_painted_.load(std::memory_order_relaxed) == 0) {
+      throw std::runtime_error(
+          "Remote framebuffer has not received its first paint yet");
+    }
 
-  {
-    std::lock_guard<std::mutex> frame_lock(frame_mutex_);
-    if (!first_frame_consumed_ && first_frame_.has_value()) {
-      first_frame_consumed_ = true;
-      return *first_frame_;
+    std::unique_lock<std::mutex> frame_lock(frame_mutex_);
+    const auto now = std::chrono::steady_clock::now();
+    const auto quiet_until =
+        std::max(started, last_frame_update_) + kScreenshotQuietPeriod;
+    auto wake_at = std::min(quiet_until, deadline);
+    if (now >= wake_at) {
+      // Copy the live buffer even on the first screenshot; a cached first paint
+      // can be partial or stale by the time the caller requests a screenshot.
+      if (auto frame = CaptureNonBlackFramebuffer(*instance_->context->gdi)) {
+        return std::move(*frame);
+      }
+      if (now >= deadline) {
+        throw std::runtime_error(
+            "RDP screenshot was still black after waiting for framebuffer updates");
+      }
+      wake_at = deadline;
     }
-  }
 
-  rdpGdi* gdi = instance_->context->gdi;
-  if (!gdi->primary_buffer || gdi->width <= 0 || gdi->height <= 0 || gdi->stride == 0) {
-    throw std::runtime_error("Remote framebuffer is empty");
+    // Let the event loop process paints while waiting. Every screenshot gets a
+    // short settling window, but animations cannot extend the total deadline.
+    lock.unlock();
+    frame_cv_.wait_until(frame_lock, wake_at);
   }
-
-  RawFrame frame;
-  frame.size.width = gdi->width;
-  frame.size.height = gdi->height;
-  frame.stride = static_cast<size_t>(gdi->stride);
-  const size_t buffer_size = frame.stride * static_cast<size_t>(gdi->height);
-  frame.bgra.assign(gdi->primary_buffer, gdi->primary_buffer + buffer_size);
-  return frame;
 }
 
 Size FreeRdpSessionTransport::GetSize() {
@@ -1360,8 +1391,7 @@ void FreeRdpSessionTransport::ResetStateLocked() {
   framebuffer_updates_.store(0, std::memory_order_relaxed);
   {
     std::lock_guard<std::mutex> frame_lock(frame_mutex_);
-    first_frame_.reset();
-    first_frame_consumed_ = false;
+    last_frame_update_ = {};
   }
   original_end_paint_ = nullptr;
   mouse_x_ = 0;
@@ -1388,23 +1418,21 @@ BOOL FreeRdpSessionTransport::CallOriginalEndPaint(rdpContext* context) {
   return TRUE;
 }
 
-void FreeRdpSessionTransport::MarkFramePainted(
-    std::optional<RawFrame> first_frame) {
+void FreeRdpSessionTransport::MarkFramePainted() {
   {
     std::lock_guard<std::mutex> lock(frame_mutex_);
-    if (first_frame.has_value() &&
-        frames_painted_.load(std::memory_order_relaxed) == 0 &&
-        !first_frame_.has_value()) {
-      first_frame_ = std::move(*first_frame);
-      first_frame_consumed_ = false;
-    }
     frames_painted_.fetch_add(1, std::memory_order_relaxed);
   }
   frame_cv_.notify_all();
 }
 
 void FreeRdpSessionTransport::MarkFramebufferUpdated() {
-  framebuffer_updates_.fetch_add(1, std::memory_order_relaxed);
+  {
+    std::lock_guard<std::mutex> lock(frame_mutex_);
+    framebuffer_updates_.fetch_add(1, std::memory_order_relaxed);
+    last_frame_update_ = std::chrono::steady_clock::now();
+  }
+  frame_cv_.notify_all();
 }
 
 bool FreeRdpSessionTransport::HasFramePainted() const {

package/native/rdp/tests/screenshot_test.cpp

@@ -0,0 +1,225 @@
+#include <algorithm>
+#include <chrono>
+#include <future>
+#include <iostream>
+#include <stdexcept>
+#include <string>
+#include <thread>
+
+#include <freerdp/gdi/gdi.h>
+
+#include "rdp_helper_session.hpp"
+
+namespace midscene::rdp {
+
+// Supply a framebuffer without a Windows server, but exercise the real
+// CaptureFrame(), paint notifications, locks, and disconnect wakeups.
+struct RdpScreenshotTestPeer {
+  FreeRdpSessionTransport transport;
+  freerdp instance{};
+  rdpContext context{};
+  rdpGdi gdi{};
+  std::vector<uint8_t> pixels;
+
+  RdpScreenshotTestPeer() : pixels(36 * 8, 255) {
+    gdi.width = 8;
+    gdi.height = 8;
+    gdi.stride = 36;  // Non-black padding must not affect black detection.
+    gdi.primary_buffer = pixels.data();
+    context.gdi = &gdi;
+    instance.context = &context;
+    transport.instance_ = &instance;
+    transport.connected_ = true;
+    transport.running_ = true;
+    transport.session_active_.store(true);
+  }
+
+  ~RdpScreenshotTestPeer() {
+    // These FreeRDP structs belong to the fixture, not freerdp_new().
+    transport.instance_ = nullptr;
+  }
+
+  void Paint(uint8_t color, int rows = 8) {
+    std::lock_guard<std::mutex> lock(transport.mutex_);
+    for (int y = 0; y < 8; ++y) {
+      for (int x = 0; x < 8; ++x) {
+        const size_t offset = y * gdi.stride + x * 4;
+        std::fill_n(pixels.data() + offset, 3, y < rows ? color : 0);
+      }
+    }
+    transport.MarkFramebufferUpdated();
+    transport.MarkFramePainted();
+  }
+
+  void LoseSession() {
+    {
+      std::lock_guard<std::mutex> lock(transport.mutex_);
+      transport.connected_ = false;
+      transport.last_error_ = ErrorPayload{"session_lost", "test disconnect"};
+    }
+    transport.SignalSessionInactive();
+  }
+};
+
+}  // namespace midscene::rdp
+
+namespace {
+
+using namespace std::chrono_literals;
+using midscene::rdp::RawFrame;
+using midscene::rdp::RdpScreenshotTestPeer;
+
+void Expect(bool condition, const char* message) {
+  if (!condition) {
+    throw std::runtime_error(message);
+  }
+}
+
+bool HasColor(const RawFrame& frame, uint8_t color) {
+  for (int y = 0; y < frame.size.height; ++y) {
+    for (int x = 0; x < frame.size.width; ++x) {
+      const size_t offset = y * frame.stride + x * 4;
+      for (size_t channel = 0; channel < 3; ++channel) {
+        if (frame.bgra[offset + channel] != color) {
+          return false;
+        }
+      }
+    }
+  }
+  return true;
+}
+
+void TestPartialFirstPaint() {
+  RdpScreenshotTestPeer peer;
+  peer.Paint(64, 2);
+  auto painting = std::async(std::launch::async, [&] {
+    // Keep painting beyond the initial quiet window: each update must extend
+    // settling, while still letting the event-loop mutex make progress.
+    for (int rows = 3; rows <= 6; ++rows) {
+      std::this_thread::sleep_for(100ms);
+      peer.Paint(128, rows);
+    }
+    std::this_thread::sleep_for(100ms);
+    peer.Paint(192);
+  });
+  const auto frame = peer.transport.CaptureFrame();
+  painting.get();
+  Expect(HasColor(frame, 192), "first screenshot returned a partial old paint");
+}
+
+void TestLaterScreenshotAndBlackRecovery() {
+  RdpScreenshotTestPeer peer;
+  peer.Paint(64);
+  Expect(HasColor(peer.transport.CaptureFrame(), 64),
+         "uniform non-black screen should be accepted");
+  peer.Paint(0);
+  auto painting = std::async(std::launch::async, [&] {
+    // Stay black beyond the quiet period; the screenshot must await recovery.
+    std::this_thread::sleep_for(500ms);
+    peer.Paint(128);
+  });
+  const auto frame = peer.transport.CaptureFrame();
+  painting.get();
+  Expect(HasColor(frame, 128), "later screenshot returned a black or cached frame");
+}
+
+void TestContinuousUpdatesHaveDeadline() {
+  RdpScreenshotTestPeer peer;
+  peer.Paint(64);
+  std::atomic<bool> stop{false};
+  auto painting = std::async(std::launch::async, [&] {
+    while (!stop.load()) {
+      peer.Paint(128);
+      std::this_thread::sleep_for(30ms);
+    }
+  });
+  auto capture = std::async(std::launch::async,
+                            [&] { return peer.transport.CaptureFrame(); });
+  const auto status = capture.wait_for(5s);
+  stop.store(true);
+  painting.get();
+  Expect(status == std::future_status::ready,
+         "continuous updates extended the screenshot deadline");
+  Expect(HasColor(capture.get(), 128), "deadline did not return the live frame");
+}
+
+void TestBlackTimeout() {
+  RdpScreenshotTestPeer peer;
+  peer.Paint(0);
+  auto capture = std::async(std::launch::async, [&] {
+    try {
+      peer.transport.CaptureFrame();
+      return std::string();
+    } catch (const std::exception& error) {
+      return std::string(error.what());
+    }
+  });
+  Expect(capture.wait_for(500ms) == std::future_status::timeout,
+         "black framebuffer was not given time to recover");
+  const auto status = capture.wait_for(5s);
+  if (status != std::future_status::ready) {
+    peer.LoseSession();
+  }
+  Expect(status == std::future_status::ready, "black screenshot never timed out");
+  Expect(capture.get().find("still black") != std::string::npos,
+         "black framebuffer (with opaque alpha and padding) was not rejected");
+}
+
+void TestDisconnectWakesScreenshot(uint8_t color) {
+  RdpScreenshotTestPeer peer;
+  peer.Paint(color);
+  auto capture = std::async(std::launch::async, [&] {
+    try {
+      peer.transport.CaptureFrame();
+      return std::string();
+    } catch (const std::exception& error) {
+      return std::string(error.what());
+    }
+  });
+  Expect(capture.wait_for(50ms) == std::future_status::timeout,
+         "screenshot did not wait for framebuffer updates");
+  peer.LoseSession();
+  Expect(capture.wait_for(1s) == std::future_status::ready,
+         "session loss did not wake the screenshot waiter");
+  Expect(capture.get().find("test disconnect") != std::string::npos,
+         "screenshot lost the session failure reason");
+}
+
+void TestInvalidFramebuffer() {
+  for (int invalid_case = 0; invalid_case < 4; ++invalid_case) {
+    RdpScreenshotTestPeer peer;
+    peer.Paint(64);
+    switch (invalid_case) {
+      case 0: peer.gdi.primary_buffer = nullptr; break;
+      case 1: peer.gdi.width = 0; break;
+      case 2: peer.gdi.height = 0; break;
+      case 3: peer.gdi.stride = 4; break;
+    }
+    std::string error_message;
+    try {
+      peer.transport.CaptureFrame();
+    } catch (const std::exception& error) {
+      error_message = error.what();
+    }
+    Expect(error_message == "Remote framebuffer is empty or invalid",
+           "invalid framebuffer layout was not rejected");
+  }
+}
+
+}  // namespace
+
+int main() {
+  try {
+    TestPartialFirstPaint();
+    TestLaterScreenshotAndBlackRecovery();
+    TestContinuousUpdatesHaveDeadline();
+    TestBlackTimeout();
+    TestDisconnectWakesScreenshot(0);
+    TestDisconnectWakesScreenshot(64);
+    TestInvalidFramebuffer();
+    return 0;
+  } catch (const std::exception& error) {
+    std::cerr << error.what() << '\n';
+    return 1;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@midscene/computer",
-  "version": "1.12.4",
+  "version": "1.12.5-beta-20260907080441.0",
   "description": "Midscene.js Computer Desktop Automation",
   "license": "MIT",
   "repository": {
@@ -33,8 +33,8 @@
     "@computer-use/libnut": "^4.2.0",
     "clipboardy": "^4.0.0",
     "screenshot-desktop": "^1.15.3",
-    "@midscene/core": "1.12.4",
-    "@midscene/shared": "1.12.4"
+    "@midscene/core": "1.12.5-beta-20260907080441.0",
+    "@midscene/shared": "1.12.5-beta-20260907080441.0"
   },
   "optionalDependencies": {
     "node-mac-permissions": "2.5.0"