@midscene/android 1.7.4 → 1.7.5-beta-20260418223706.0

package/dist/es/cli.mjs

@@ -676,6 +676,9 @@ const defaultNormalScrollDuration = 1000;
 const IME_STRATEGY_ALWAYS_YADB = 'always-yadb';
 const IME_STRATEGY_YADB_FOR_NON_ASCII = 'yadb-for-non-ascii';
 const debugDevice = (0, logger_.getDebug)('android:device');
+const warnDevice = (0, logger_.getDebug)('android:device', {
+    console: true
+});
 function escapeForShell(text) {
     return text.replace(/'/g, "'\\''").replace(/\n/g, '\\n');
 }
@@ -855,7 +858,7 @@ class AndroidDevice {
             console.log(`[midscene] Using scrcpy for screenshots (device: ${this.deviceId})`);
         } catch (error) {
             const msg = error instanceof Error ? error.message : String(error);
-            console.warn(`[midscene] Scrcpy unavailable, using ADB fallback (device: ${this.deviceId}): ${msg}`);
+            warnDevice(`[midscene] Scrcpy unavailable, using ADB fallback (device: ${this.deviceId}): ${msg}`);
         }
         return adb;
     }
@@ -1223,6 +1226,22 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
             y: endY
         };
     }
+    warnScrollDistanceClamped(direction, requestedDistance, appliedDistance) {
+        if (requestedDistance <= appliedDistance) return;
+        const scrollToSuggestion = {
+            down: 'scrollToBottom',
+            up: 'scrollToTop',
+            left: 'scrollToLeft',
+            right: 'scrollToRight'
+        };
+        const edgeLabel = {
+            down: 'bottom',
+            up: 'top',
+            left: 'left edge',
+            right: 'right edge'
+        };
+        warnDevice(`[midscene] Android ADB swipe coordinates must stay within the screen bounds. The requested scroll distance (${requestedDistance}px) exceeds the maximum single swipe distance (${appliedDistance}px) from the current start point, so it will be clamped. If you want to scroll to the ${edgeLabel[direction]}, use ${scrollToSuggestion[direction]} instead.`);
+    }
     async screenshotBase64() {
         debugDevice('screenshotBase64 begin');
         const adapter = this.getScrcpyAdapter();
@@ -1407,58 +1426,66 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
     async scrollUp(distance, startPoint) {
         const { height } = await this.size();
         const scrollDistance = Math.round(distance || height);
+        const hasExplicitDistance = void 0 !== distance;
         if (startPoint) {
             const start = {
                 x: Math.round(startPoint.left),
                 y: Math.round(startPoint.top)
             };
             const end = this.calculateScrollEndPoint(start, 0, scrollDistance, 0, height);
+            if (hasExplicitDistance) this.warnScrollDistanceClamped('up', scrollDistance, Math.abs(end.y - start.y));
             await this.mouseDrag(start, end);
             return;
         }
-        await this.scroll(0, -scrollDistance);
+        await this.scroll(0, -scrollDistance, void 0, hasExplicitDistance, 'up');
     }
     async scrollDown(distance, startPoint) {
         const { height } = await this.size();
         const scrollDistance = Math.round(distance || height);
+        const hasExplicitDistance = void 0 !== distance;
         if (startPoint) {
             const start = {
                 x: Math.round(startPoint.left),
                 y: Math.round(startPoint.top)
             };
             const end = this.calculateScrollEndPoint(start, 0, -scrollDistance, 0, height);
+            if (hasExplicitDistance) this.warnScrollDistanceClamped('down', scrollDistance, Math.abs(end.y - start.y));
             await this.mouseDrag(start, end);
             return;
         }
-        await this.scroll(0, scrollDistance);
+        await this.scroll(0, scrollDistance, void 0, hasExplicitDistance, 'down');
     }
     async scrollLeft(distance, startPoint) {
         const { width } = await this.size();
         const scrollDistance = Math.round(distance || width);
+        const hasExplicitDistance = void 0 !== distance;
         if (startPoint) {
             const start = {
                 x: Math.round(startPoint.left),
                 y: Math.round(startPoint.top)
             };
             const end = this.calculateScrollEndPoint(start, scrollDistance, 0, width, 0);
+            if (hasExplicitDistance) this.warnScrollDistanceClamped('left', scrollDistance, Math.abs(end.x - start.x));
             await this.mouseDrag(start, end);
             return;
         }
-        await this.scroll(-scrollDistance, 0);
+        await this.scroll(-scrollDistance, 0, void 0, hasExplicitDistance, 'left');
     }
     async scrollRight(distance, startPoint) {
         const { width } = await this.size();
         const scrollDistance = Math.round(distance || width);
+        const hasExplicitDistance = void 0 !== distance;
         if (startPoint) {
             const start = {
                 x: Math.round(startPoint.left),
                 y: Math.round(startPoint.top)
             };
             const end = this.calculateScrollEndPoint(start, -scrollDistance, 0, width, 0);
+            if (hasExplicitDistance) this.warnScrollDistanceClamped('right', scrollDistance, Math.abs(end.x - start.x));
             await this.mouseDrag(start, end);
             return;
         }
-        await this.scroll(scrollDistance, 0);
+        await this.scroll(scrollDistance, 0, void 0, hasExplicitDistance, 'right');
     }
     async ensureYadb() {
         if (!this.yadbPushed) {
@@ -1558,7 +1585,7 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         const swipeDuration = duration ?? defaultNormalScrollDuration;
         await adb.shell(`input${this.getDisplayArg()} swipe ${fromX} ${fromY} ${toX} ${toY} ${swipeDuration}`);
     }
-    async scroll(deltaX, deltaY, duration) {
+    async scroll(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;
@@ -1568,8 +1595,15 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         const maxNegativeDeltaX = width - startX;
         const maxPositiveDeltaY = startY;
         const maxNegativeDeltaY = height - startY;
+        const originalDeltaX = deltaX;
+        const originalDeltaY = deltaY;
         deltaX = Math.max(-maxNegativeDeltaX, Math.min(deltaX, maxPositiveDeltaX));
         deltaY = Math.max(-maxNegativeDeltaY, Math.min(deltaY, maxPositiveDeltaY));
+        if (warnOnClamp && direction && (deltaX !== originalDeltaX || deltaY !== originalDeltaY)) {
+            const requestedDistance = 'left' === direction || 'right' === direction ? Math.abs(originalDeltaX) : Math.abs(originalDeltaY);
+            const appliedDistance = 'left' === direction || 'right' === direction ? Math.abs(deltaX) : Math.abs(deltaY);
+            this.warnScrollDistanceClamped(direction, requestedDistance, appliedDistance);
+        }
         const endX = Math.round(startX - deltaX);
         const endY = Math.round(startY - deltaY);
         const { x: adjustedStartX, y: adjustedStartY } = await this.adjustCoordinates(startX, startY);
@@ -1726,7 +1760,7 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
             }
             debugDevice(`Keyboard still shown after keycode ${keyCode}, trying next key`);
         }
-        console.warn('Warning: Failed to hide the software keyboard after trying both ESC and BACK keys');
+        warnDevice('Warning: Failed to hide the software keyboard after trying both ESC and BACK keys');
         return false;
     }
     constructor(deviceId, options){
@@ -1952,7 +1986,7 @@ class AndroidMidsceneTools extends BaseMidsceneTools {
 const tools = new AndroidMidsceneTools();
 runToolsCLI(tools, 'midscene-android', {
     stripPrefix: 'android_',
-    version: "1.7.4",
+    version: "1.7.5-beta-20260418223706.0",
     extraCommands: createReportCliCommands()
 }).catch((e)=>{
     if (!(e instanceof CLIError)) console.error(e);

package/dist/es/index.mjs

@@ -579,6 +579,9 @@ const defaultNormalScrollDuration = 1000;
 const IME_STRATEGY_ALWAYS_YADB = 'always-yadb';
 const IME_STRATEGY_YADB_FOR_NON_ASCII = 'yadb-for-non-ascii';
 const debugDevice = (0, logger_.getDebug)('android:device');
+const warnDevice = (0, logger_.getDebug)('android:device', {
+    console: true
+});
 function escapeForShell(text) {
     return text.replace(/'/g, "'\\''").replace(/\n/g, '\\n');
 }
@@ -758,7 +761,7 @@ class AndroidDevice {
             console.log(`[midscene] Using scrcpy for screenshots (device: ${this.deviceId})`);
         } catch (error) {
             const msg = error instanceof Error ? error.message : String(error);
-            console.warn(`[midscene] Scrcpy unavailable, using ADB fallback (device: ${this.deviceId}): ${msg}`);
+            warnDevice(`[midscene] Scrcpy unavailable, using ADB fallback (device: ${this.deviceId}): ${msg}`);
         }
         return adb;
     }
@@ -1126,6 +1129,22 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
             y: endY
         };
     }
+    warnScrollDistanceClamped(direction, requestedDistance, appliedDistance) {
+        if (requestedDistance <= appliedDistance) return;
+        const scrollToSuggestion = {
+            down: 'scrollToBottom',
+            up: 'scrollToTop',
+            left: 'scrollToLeft',
+            right: 'scrollToRight'
+        };
+        const edgeLabel = {
+            down: 'bottom',
+            up: 'top',
+            left: 'left edge',
+            right: 'right edge'
+        };
+        warnDevice(`[midscene] Android ADB swipe coordinates must stay within the screen bounds. The requested scroll distance (${requestedDistance}px) exceeds the maximum single swipe distance (${appliedDistance}px) from the current start point, so it will be clamped. If you want to scroll to the ${edgeLabel[direction]}, use ${scrollToSuggestion[direction]} instead.`);
+    }
     async screenshotBase64() {
         debugDevice('screenshotBase64 begin');
         const adapter = this.getScrcpyAdapter();
@@ -1310,58 +1329,66 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
     async scrollUp(distance, startPoint) {
         const { height } = await this.size();
         const scrollDistance = Math.round(distance || height);
+        const hasExplicitDistance = void 0 !== distance;
         if (startPoint) {
             const start = {
                 x: Math.round(startPoint.left),
                 y: Math.round(startPoint.top)
             };
             const end = this.calculateScrollEndPoint(start, 0, scrollDistance, 0, height);
+            if (hasExplicitDistance) this.warnScrollDistanceClamped('up', scrollDistance, Math.abs(end.y - start.y));
             await this.mouseDrag(start, end);
             return;
         }
-        await this.scroll(0, -scrollDistance);
+        await this.scroll(0, -scrollDistance, void 0, hasExplicitDistance, 'up');
     }
     async scrollDown(distance, startPoint) {
         const { height } = await this.size();
         const scrollDistance = Math.round(distance || height);
+        const hasExplicitDistance = void 0 !== distance;
         if (startPoint) {
             const start = {
                 x: Math.round(startPoint.left),
                 y: Math.round(startPoint.top)
             };
             const end = this.calculateScrollEndPoint(start, 0, -scrollDistance, 0, height);
+            if (hasExplicitDistance) this.warnScrollDistanceClamped('down', scrollDistance, Math.abs(end.y - start.y));
             await this.mouseDrag(start, end);
             return;
         }
-        await this.scroll(0, scrollDistance);
+        await this.scroll(0, scrollDistance, void 0, hasExplicitDistance, 'down');
     }
     async scrollLeft(distance, startPoint) {
         const { width } = await this.size();
         const scrollDistance = Math.round(distance || width);
+        const hasExplicitDistance = void 0 !== distance;
         if (startPoint) {
             const start = {
                 x: Math.round(startPoint.left),
                 y: Math.round(startPoint.top)
             };
             const end = this.calculateScrollEndPoint(start, scrollDistance, 0, width, 0);
+            if (hasExplicitDistance) this.warnScrollDistanceClamped('left', scrollDistance, Math.abs(end.x - start.x));
             await this.mouseDrag(start, end);
             return;
         }
-        await this.scroll(-scrollDistance, 0);
+        await this.scroll(-scrollDistance, 0, void 0, hasExplicitDistance, 'left');
     }
     async scrollRight(distance, startPoint) {
         const { width } = await this.size();
         const scrollDistance = Math.round(distance || width);
+        const hasExplicitDistance = void 0 !== distance;
         if (startPoint) {
             const start = {
                 x: Math.round(startPoint.left),
                 y: Math.round(startPoint.top)
             };
             const end = this.calculateScrollEndPoint(start, -scrollDistance, 0, width, 0);
+            if (hasExplicitDistance) this.warnScrollDistanceClamped('right', scrollDistance, Math.abs(end.x - start.x));
             await this.mouseDrag(start, end);
             return;
         }
-        await this.scroll(scrollDistance, 0);
+        await this.scroll(scrollDistance, 0, void 0, hasExplicitDistance, 'right');
     }
     async ensureYadb() {
         if (!this.yadbPushed) {
@@ -1461,7 +1488,7 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         const swipeDuration = duration ?? defaultNormalScrollDuration;
         await adb.shell(`input${this.getDisplayArg()} swipe ${fromX} ${fromY} ${toX} ${toY} ${swipeDuration}`);
     }
-    async scroll(deltaX, deltaY, duration) {
+    async scroll(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;
@@ -1471,8 +1498,15 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         const maxNegativeDeltaX = width - startX;
         const maxPositiveDeltaY = startY;
         const maxNegativeDeltaY = height - startY;
+        const originalDeltaX = deltaX;
+        const originalDeltaY = deltaY;
         deltaX = Math.max(-maxNegativeDeltaX, Math.min(deltaX, maxPositiveDeltaX));
         deltaY = Math.max(-maxNegativeDeltaY, Math.min(deltaY, maxPositiveDeltaY));
+        if (warnOnClamp && direction && (deltaX !== originalDeltaX || deltaY !== originalDeltaY)) {
+            const requestedDistance = 'left' === direction || 'right' === direction ? Math.abs(originalDeltaX) : Math.abs(originalDeltaY);
+            const appliedDistance = 'left' === direction || 'right' === direction ? Math.abs(deltaX) : Math.abs(deltaY);
+            this.warnScrollDistanceClamped(direction, requestedDistance, appliedDistance);
+        }
         const endX = Math.round(startX - deltaX);
         const endY = Math.round(startY - deltaY);
         const { x: adjustedStartX, y: adjustedStartY } = await this.adjustCoordinates(startX, startY);
@@ -1629,7 +1663,7 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
             }
             debugDevice(`Keyboard still shown after keycode ${keyCode}, trying next key`);
         }
-        console.warn('Warning: Failed to hide the software keyboard after trying both ESC and BACK keys');
+        warnDevice('Warning: Failed to hide the software keyboard after trying both ESC and BACK keys');
         return false;
     }
     constructor(deviceId, options){

package/dist/es/mcp-server.mjs

@@ -675,6 +675,9 @@ const defaultNormalScrollDuration = 1000;
 const IME_STRATEGY_ALWAYS_YADB = 'always-yadb';
 const IME_STRATEGY_YADB_FOR_NON_ASCII = 'yadb-for-non-ascii';
 const debugDevice = (0, logger_.getDebug)('android:device');
+const warnDevice = (0, logger_.getDebug)('android:device', {
+    console: true
+});
 function escapeForShell(text) {
     return text.replace(/'/g, "'\\''").replace(/\n/g, '\\n');
 }
@@ -854,7 +857,7 @@ class AndroidDevice {
             console.log(`[midscene] Using scrcpy for screenshots (device: ${this.deviceId})`);
         } catch (error) {
             const msg = error instanceof Error ? error.message : String(error);
-            console.warn(`[midscene] Scrcpy unavailable, using ADB fallback (device: ${this.deviceId}): ${msg}`);
+            warnDevice(`[midscene] Scrcpy unavailable, using ADB fallback (device: ${this.deviceId}): ${msg}`);
         }
         return adb;
     }
@@ -1222,6 +1225,22 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
             y: endY
         };
     }
+    warnScrollDistanceClamped(direction, requestedDistance, appliedDistance) {
+        if (requestedDistance <= appliedDistance) return;
+        const scrollToSuggestion = {
+            down: 'scrollToBottom',
+            up: 'scrollToTop',
+            left: 'scrollToLeft',
+            right: 'scrollToRight'
+        };
+        const edgeLabel = {
+            down: 'bottom',
+            up: 'top',
+            left: 'left edge',
+            right: 'right edge'
+        };
+        warnDevice(`[midscene] Android ADB swipe coordinates must stay within the screen bounds. The requested scroll distance (${requestedDistance}px) exceeds the maximum single swipe distance (${appliedDistance}px) from the current start point, so it will be clamped. If you want to scroll to the ${edgeLabel[direction]}, use ${scrollToSuggestion[direction]} instead.`);
+    }
     async screenshotBase64() {
         debugDevice('screenshotBase64 begin');
         const adapter = this.getScrcpyAdapter();
@@ -1406,58 +1425,66 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
     async scrollUp(distance, startPoint) {
         const { height } = await this.size();
         const scrollDistance = Math.round(distance || height);
+        const hasExplicitDistance = void 0 !== distance;
         if (startPoint) {
             const start = {
                 x: Math.round(startPoint.left),
                 y: Math.round(startPoint.top)
             };
             const end = this.calculateScrollEndPoint(start, 0, scrollDistance, 0, height);
+            if (hasExplicitDistance) this.warnScrollDistanceClamped('up', scrollDistance, Math.abs(end.y - start.y));
             await this.mouseDrag(start, end);
             return;
         }
-        await this.scroll(0, -scrollDistance);
+        await this.scroll(0, -scrollDistance, void 0, hasExplicitDistance, 'up');
     }
     async scrollDown(distance, startPoint) {
         const { height } = await this.size();
         const scrollDistance = Math.round(distance || height);
+        const hasExplicitDistance = void 0 !== distance;
         if (startPoint) {
             const start = {
                 x: Math.round(startPoint.left),
                 y: Math.round(startPoint.top)
             };
             const end = this.calculateScrollEndPoint(start, 0, -scrollDistance, 0, height);
+            if (hasExplicitDistance) this.warnScrollDistanceClamped('down', scrollDistance, Math.abs(end.y - start.y));
             await this.mouseDrag(start, end);
             return;
         }
-        await this.scroll(0, scrollDistance);
+        await this.scroll(0, scrollDistance, void 0, hasExplicitDistance, 'down');
     }
     async scrollLeft(distance, startPoint) {
         const { width } = await this.size();
         const scrollDistance = Math.round(distance || width);
+        const hasExplicitDistance = void 0 !== distance;
         if (startPoint) {
             const start = {
                 x: Math.round(startPoint.left),
                 y: Math.round(startPoint.top)
             };
             const end = this.calculateScrollEndPoint(start, scrollDistance, 0, width, 0);
+            if (hasExplicitDistance) this.warnScrollDistanceClamped('left', scrollDistance, Math.abs(end.x - start.x));
             await this.mouseDrag(start, end);
             return;
         }
-        await this.scroll(-scrollDistance, 0);
+        await this.scroll(-scrollDistance, 0, void 0, hasExplicitDistance, 'left');
     }
     async scrollRight(distance, startPoint) {
         const { width } = await this.size();
         const scrollDistance = Math.round(distance || width);
+        const hasExplicitDistance = void 0 !== distance;
         if (startPoint) {
             const start = {
                 x: Math.round(startPoint.left),
                 y: Math.round(startPoint.top)
             };
             const end = this.calculateScrollEndPoint(start, -scrollDistance, 0, width, 0);
+            if (hasExplicitDistance) this.warnScrollDistanceClamped('right', scrollDistance, Math.abs(end.x - start.x));
             await this.mouseDrag(start, end);
             return;
         }
-        await this.scroll(scrollDistance, 0);
+        await this.scroll(scrollDistance, 0, void 0, hasExplicitDistance, 'right');
     }
     async ensureYadb() {
         if (!this.yadbPushed) {
@@ -1557,7 +1584,7 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         const swipeDuration = duration ?? defaultNormalScrollDuration;
         await adb.shell(`input${this.getDisplayArg()} swipe ${fromX} ${fromY} ${toX} ${toY} ${swipeDuration}`);
     }
-    async scroll(deltaX, deltaY, duration) {
+    async scroll(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;
@@ -1567,8 +1594,15 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         const maxNegativeDeltaX = width - startX;
         const maxPositiveDeltaY = startY;
         const maxNegativeDeltaY = height - startY;
+        const originalDeltaX = deltaX;
+        const originalDeltaY = deltaY;
         deltaX = Math.max(-maxNegativeDeltaX, Math.min(deltaX, maxPositiveDeltaX));
         deltaY = Math.max(-maxNegativeDeltaY, Math.min(deltaY, maxPositiveDeltaY));
+        if (warnOnClamp && direction && (deltaX !== originalDeltaX || deltaY !== originalDeltaY)) {
+            const requestedDistance = 'left' === direction || 'right' === direction ? Math.abs(originalDeltaX) : Math.abs(originalDeltaY);
+            const appliedDistance = 'left' === direction || 'right' === direction ? Math.abs(deltaX) : Math.abs(deltaY);
+            this.warnScrollDistanceClamped(direction, requestedDistance, appliedDistance);
+        }
         const endX = Math.round(startX - deltaX);
         const endY = Math.round(startY - deltaY);
         const { x: adjustedStartX, y: adjustedStartY } = await this.adjustCoordinates(startX, startY);
@@ -1725,7 +1759,7 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
             }
             debugDevice(`Keyboard still shown after keycode ${keyCode}, trying next key`);
         }
-        console.warn('Warning: Failed to hide the software keyboard after trying both ESC and BACK keys');
+        warnDevice('Warning: Failed to hide the software keyboard after trying both ESC and BACK keys');
         return false;
     }
     constructor(deviceId, options){
@@ -1955,7 +1989,7 @@ class AndroidMCPServer extends BaseMCPServer {
     constructor(toolsManager){
         super({
             name: '@midscene/android-mcp',
-            version: "1.7.4",
+            version: "1.7.5-beta-20260418223706.0",
             description: 'Control the Android device using natural language commands'
         }, toolsManager);
     }

package/dist/lib/cli.js

@@ -691,6 +691,9 @@ var __webpack_exports__ = {};
     const IME_STRATEGY_ALWAYS_YADB = 'always-yadb';
     const IME_STRATEGY_YADB_FOR_NON_ASCII = 'yadb-for-non-ascii';
     const debugDevice = (0, logger_.getDebug)('android:device');
+    const warnDevice = (0, logger_.getDebug)('android:device', {
+        console: true
+    });
     function escapeForShell(text) {
         return text.replace(/'/g, "'\\''").replace(/\n/g, '\\n');
     }
@@ -870,7 +873,7 @@ var __webpack_exports__ = {};
                 console.log(`[midscene] Using scrcpy for screenshots (device: ${this.deviceId})`);
             } catch (error) {
                 const msg = error instanceof Error ? error.message : String(error);
-                console.warn(`[midscene] Scrcpy unavailable, using ADB fallback (device: ${this.deviceId}): ${msg}`);
+                warnDevice(`[midscene] Scrcpy unavailable, using ADB fallback (device: ${this.deviceId}): ${msg}`);
             }
             return adb;
         }
@@ -1238,6 +1241,22 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
                 y: endY
             };
         }
+        warnScrollDistanceClamped(direction, requestedDistance, appliedDistance) {
+            if (requestedDistance <= appliedDistance) return;
+            const scrollToSuggestion = {
+                down: 'scrollToBottom',
+                up: 'scrollToTop',
+                left: 'scrollToLeft',
+                right: 'scrollToRight'
+            };
+            const edgeLabel = {
+                down: 'bottom',
+                up: 'top',
+                left: 'left edge',
+                right: 'right edge'
+            };
+            warnDevice(`[midscene] Android ADB swipe coordinates must stay within the screen bounds. The requested scroll distance (${requestedDistance}px) exceeds the maximum single swipe distance (${appliedDistance}px) from the current start point, so it will be clamped. If you want to scroll to the ${edgeLabel[direction]}, use ${scrollToSuggestion[direction]} instead.`);
+        }
         async screenshotBase64() {
             debugDevice('screenshotBase64 begin');
             const adapter = this.getScrcpyAdapter();
@@ -1422,58 +1441,66 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         async scrollUp(distance, startPoint) {
             const { height } = await this.size();
             const scrollDistance = Math.round(distance || height);
+            const hasExplicitDistance = void 0 !== distance;
             if (startPoint) {
                 const start = {
                     x: Math.round(startPoint.left),
                     y: Math.round(startPoint.top)
                 };
                 const end = this.calculateScrollEndPoint(start, 0, scrollDistance, 0, height);
+                if (hasExplicitDistance) this.warnScrollDistanceClamped('up', scrollDistance, Math.abs(end.y - start.y));
                 await this.mouseDrag(start, end);
                 return;
             }
-            await this.scroll(0, -scrollDistance);
+            await this.scroll(0, -scrollDistance, void 0, hasExplicitDistance, 'up');
         }
         async scrollDown(distance, startPoint) {
             const { height } = await this.size();
             const scrollDistance = Math.round(distance || height);
+            const hasExplicitDistance = void 0 !== distance;
             if (startPoint) {
                 const start = {
                     x: Math.round(startPoint.left),
                     y: Math.round(startPoint.top)
                 };
                 const end = this.calculateScrollEndPoint(start, 0, -scrollDistance, 0, height);
+                if (hasExplicitDistance) this.warnScrollDistanceClamped('down', scrollDistance, Math.abs(end.y - start.y));
                 await this.mouseDrag(start, end);
                 return;
             }
-            await this.scroll(0, scrollDistance);
+            await this.scroll(0, scrollDistance, void 0, hasExplicitDistance, 'down');
         }
         async scrollLeft(distance, startPoint) {
             const { width } = await this.size();
             const scrollDistance = Math.round(distance || width);
+            const hasExplicitDistance = void 0 !== distance;
             if (startPoint) {
                 const start = {
                     x: Math.round(startPoint.left),
                     y: Math.round(startPoint.top)
                 };
                 const end = this.calculateScrollEndPoint(start, scrollDistance, 0, width, 0);
+                if (hasExplicitDistance) this.warnScrollDistanceClamped('left', scrollDistance, Math.abs(end.x - start.x));
                 await this.mouseDrag(start, end);
                 return;
             }
-            await this.scroll(-scrollDistance, 0);
+            await this.scroll(-scrollDistance, 0, void 0, hasExplicitDistance, 'left');
         }
         async scrollRight(distance, startPoint) {
             const { width } = await this.size();
             const scrollDistance = Math.round(distance || width);
+            const hasExplicitDistance = void 0 !== distance;
             if (startPoint) {
                 const start = {
                     x: Math.round(startPoint.left),
                     y: Math.round(startPoint.top)
                 };
                 const end = this.calculateScrollEndPoint(start, -scrollDistance, 0, width, 0);
+                if (hasExplicitDistance) this.warnScrollDistanceClamped('right', scrollDistance, Math.abs(end.x - start.x));
                 await this.mouseDrag(start, end);
                 return;
             }
-            await this.scroll(scrollDistance, 0);
+            await this.scroll(scrollDistance, 0, void 0, hasExplicitDistance, 'right');
         }
         async ensureYadb() {
             if (!this.yadbPushed) {
@@ -1573,7 +1600,7 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
             const swipeDuration = duration ?? defaultNormalScrollDuration;
             await adb.shell(`input${this.getDisplayArg()} swipe ${fromX} ${fromY} ${toX} ${toY} ${swipeDuration}`);
         }
-        async scroll(deltaX, deltaY, duration) {
+        async scroll(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;
@@ -1583,8 +1610,15 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
             const maxNegativeDeltaX = width - startX;
             const maxPositiveDeltaY = startY;
             const maxNegativeDeltaY = height - startY;
+            const originalDeltaX = deltaX;
+            const originalDeltaY = deltaY;
             deltaX = Math.max(-maxNegativeDeltaX, Math.min(deltaX, maxPositiveDeltaX));
             deltaY = Math.max(-maxNegativeDeltaY, Math.min(deltaY, maxPositiveDeltaY));
+            if (warnOnClamp && direction && (deltaX !== originalDeltaX || deltaY !== originalDeltaY)) {
+                const requestedDistance = 'left' === direction || 'right' === direction ? Math.abs(originalDeltaX) : Math.abs(originalDeltaY);
+                const appliedDistance = 'left' === direction || 'right' === direction ? Math.abs(deltaX) : Math.abs(deltaY);
+                this.warnScrollDistanceClamped(direction, requestedDistance, appliedDistance);
+            }
             const endX = Math.round(startX - deltaX);
             const endY = Math.round(startY - deltaY);
             const { x: adjustedStartX, y: adjustedStartY } = await this.adjustCoordinates(startX, startY);
@@ -1741,7 +1775,7 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
                 }
                 debugDevice(`Keyboard still shown after keycode ${keyCode}, trying next key`);
             }
-            console.warn('Warning: Failed to hide the software keyboard after trying both ESC and BACK keys');
+            warnDevice('Warning: Failed to hide the software keyboard after trying both ESC and BACK keys');
             return false;
         }
         constructor(deviceId, options){
@@ -1967,7 +2001,7 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
     const tools = new AndroidMidsceneTools();
     (0, cli_namespaceObject.runToolsCLI)(tools, 'midscene-android', {
         stripPrefix: 'android_',
-        version: "1.7.4",
+        version: "1.7.5-beta-20260418223706.0",
         extraCommands: (0, core_namespaceObject.createReportCliCommands)()
     }).catch((e)=>{
         if (!(e instanceof cli_namespaceObject.CLIError)) console.error(e);

package/dist/lib/index.js

@@ -613,6 +613,9 @@ var __webpack_exports__ = {};
     const IME_STRATEGY_ALWAYS_YADB = 'always-yadb';
     const IME_STRATEGY_YADB_FOR_NON_ASCII = 'yadb-for-non-ascii';
     const debugDevice = (0, logger_.getDebug)('android:device');
+    const warnDevice = (0, logger_.getDebug)('android:device', {
+        console: true
+    });
     function escapeForShell(text) {
         return text.replace(/'/g, "'\\''").replace(/\n/g, '\\n');
     }
@@ -792,7 +795,7 @@ var __webpack_exports__ = {};
                 console.log(`[midscene] Using scrcpy for screenshots (device: ${this.deviceId})`);
             } catch (error) {
                 const msg = error instanceof Error ? error.message : String(error);
-                console.warn(`[midscene] Scrcpy unavailable, using ADB fallback (device: ${this.deviceId}): ${msg}`);
+                warnDevice(`[midscene] Scrcpy unavailable, using ADB fallback (device: ${this.deviceId}): ${msg}`);
             }
             return adb;
         }
@@ -1160,6 +1163,22 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
                 y: endY
             };
         }
+        warnScrollDistanceClamped(direction, requestedDistance, appliedDistance) {
+            if (requestedDistance <= appliedDistance) return;
+            const scrollToSuggestion = {
+                down: 'scrollToBottom',
+                up: 'scrollToTop',
+                left: 'scrollToLeft',
+                right: 'scrollToRight'
+            };
+            const edgeLabel = {
+                down: 'bottom',
+                up: 'top',
+                left: 'left edge',
+                right: 'right edge'
+            };
+            warnDevice(`[midscene] Android ADB swipe coordinates must stay within the screen bounds. The requested scroll distance (${requestedDistance}px) exceeds the maximum single swipe distance (${appliedDistance}px) from the current start point, so it will be clamped. If you want to scroll to the ${edgeLabel[direction]}, use ${scrollToSuggestion[direction]} instead.`);
+        }
         async screenshotBase64() {
             debugDevice('screenshotBase64 begin');
             const adapter = this.getScrcpyAdapter();
@@ -1344,58 +1363,66 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         async scrollUp(distance, startPoint) {
             const { height } = await this.size();
             const scrollDistance = Math.round(distance || height);
+            const hasExplicitDistance = void 0 !== distance;
             if (startPoint) {
                 const start = {
                     x: Math.round(startPoint.left),
                     y: Math.round(startPoint.top)
                 };
                 const end = this.calculateScrollEndPoint(start, 0, scrollDistance, 0, height);
+                if (hasExplicitDistance) this.warnScrollDistanceClamped('up', scrollDistance, Math.abs(end.y - start.y));
                 await this.mouseDrag(start, end);
                 return;
             }
-            await this.scroll(0, -scrollDistance);
+            await this.scroll(0, -scrollDistance, void 0, hasExplicitDistance, 'up');
         }
         async scrollDown(distance, startPoint) {
             const { height } = await this.size();
             const scrollDistance = Math.round(distance || height);
+            const hasExplicitDistance = void 0 !== distance;
             if (startPoint) {
                 const start = {
                     x: Math.round(startPoint.left),
                     y: Math.round(startPoint.top)
                 };
                 const end = this.calculateScrollEndPoint(start, 0, -scrollDistance, 0, height);
+                if (hasExplicitDistance) this.warnScrollDistanceClamped('down', scrollDistance, Math.abs(end.y - start.y));
                 await this.mouseDrag(start, end);
                 return;
             }
-            await this.scroll(0, scrollDistance);
+            await this.scroll(0, scrollDistance, void 0, hasExplicitDistance, 'down');
         }
         async scrollLeft(distance, startPoint) {
             const { width } = await this.size();
             const scrollDistance = Math.round(distance || width);
+            const hasExplicitDistance = void 0 !== distance;
             if (startPoint) {
                 const start = {
                     x: Math.round(startPoint.left),
                     y: Math.round(startPoint.top)
                 };
                 const end = this.calculateScrollEndPoint(start, scrollDistance, 0, width, 0);
+                if (hasExplicitDistance) this.warnScrollDistanceClamped('left', scrollDistance, Math.abs(end.x - start.x));
                 await this.mouseDrag(start, end);
                 return;
             }
-            await this.scroll(-scrollDistance, 0);
+            await this.scroll(-scrollDistance, 0, void 0, hasExplicitDistance, 'left');
         }
         async scrollRight(distance, startPoint) {
             const { width } = await this.size();
             const scrollDistance = Math.round(distance || width);
+            const hasExplicitDistance = void 0 !== distance;
             if (startPoint) {
                 const start = {
                     x: Math.round(startPoint.left),
                     y: Math.round(startPoint.top)
                 };
                 const end = this.calculateScrollEndPoint(start, -scrollDistance, 0, width, 0);
+                if (hasExplicitDistance) this.warnScrollDistanceClamped('right', scrollDistance, Math.abs(end.x - start.x));
                 await this.mouseDrag(start, end);
                 return;
             }
-            await this.scroll(scrollDistance, 0);
+            await this.scroll(scrollDistance, 0, void 0, hasExplicitDistance, 'right');
         }
         async ensureYadb() {
             if (!this.yadbPushed) {
@@ -1495,7 +1522,7 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
             const swipeDuration = duration ?? defaultNormalScrollDuration;
             await adb.shell(`input${this.getDisplayArg()} swipe ${fromX} ${fromY} ${toX} ${toY} ${swipeDuration}`);
         }
-        async scroll(deltaX, deltaY, duration) {
+        async scroll(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;
@@ -1505,8 +1532,15 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
             const maxNegativeDeltaX = width - startX;
             const maxPositiveDeltaY = startY;
             const maxNegativeDeltaY = height - startY;
+            const originalDeltaX = deltaX;
+            const originalDeltaY = deltaY;
             deltaX = Math.max(-maxNegativeDeltaX, Math.min(deltaX, maxPositiveDeltaX));
             deltaY = Math.max(-maxNegativeDeltaY, Math.min(deltaY, maxPositiveDeltaY));
+            if (warnOnClamp && direction && (deltaX !== originalDeltaX || deltaY !== originalDeltaY)) {
+                const requestedDistance = 'left' === direction || 'right' === direction ? Math.abs(originalDeltaX) : Math.abs(originalDeltaY);
+                const appliedDistance = 'left' === direction || 'right' === direction ? Math.abs(deltaX) : Math.abs(deltaY);
+                this.warnScrollDistanceClamped(direction, requestedDistance, appliedDistance);
+            }
             const endX = Math.round(startX - deltaX);
             const endY = Math.round(startY - deltaY);
             const { x: adjustedStartX, y: adjustedStartY } = await this.adjustCoordinates(startX, startY);
@@ -1663,7 +1697,7 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
                 }
                 debugDevice(`Keyboard still shown after keycode ${keyCode}, trying next key`);
             }
-            console.warn('Warning: Failed to hide the software keyboard after trying both ESC and BACK keys');
+            warnDevice('Warning: Failed to hide the software keyboard after trying both ESC and BACK keys');
             return false;
         }
         constructor(deviceId, options){

package/dist/lib/mcp-server.js

@@ -706,6 +706,9 @@ var __webpack_exports__ = {};
     const IME_STRATEGY_ALWAYS_YADB = 'always-yadb';
     const IME_STRATEGY_YADB_FOR_NON_ASCII = 'yadb-for-non-ascii';
     const debugDevice = (0, logger_.getDebug)('android:device');
+    const warnDevice = (0, logger_.getDebug)('android:device', {
+        console: true
+    });
     function escapeForShell(text) {
         return text.replace(/'/g, "'\\''").replace(/\n/g, '\\n');
     }
@@ -885,7 +888,7 @@ var __webpack_exports__ = {};
                 console.log(`[midscene] Using scrcpy for screenshots (device: ${this.deviceId})`);
             } catch (error) {
                 const msg = error instanceof Error ? error.message : String(error);
-                console.warn(`[midscene] Scrcpy unavailable, using ADB fallback (device: ${this.deviceId}): ${msg}`);
+                warnDevice(`[midscene] Scrcpy unavailable, using ADB fallback (device: ${this.deviceId}): ${msg}`);
             }
             return adb;
         }
@@ -1253,6 +1256,22 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
                 y: endY
             };
         }
+        warnScrollDistanceClamped(direction, requestedDistance, appliedDistance) {
+            if (requestedDistance <= appliedDistance) return;
+            const scrollToSuggestion = {
+                down: 'scrollToBottom',
+                up: 'scrollToTop',
+                left: 'scrollToLeft',
+                right: 'scrollToRight'
+            };
+            const edgeLabel = {
+                down: 'bottom',
+                up: 'top',
+                left: 'left edge',
+                right: 'right edge'
+            };
+            warnDevice(`[midscene] Android ADB swipe coordinates must stay within the screen bounds. The requested scroll distance (${requestedDistance}px) exceeds the maximum single swipe distance (${appliedDistance}px) from the current start point, so it will be clamped. If you want to scroll to the ${edgeLabel[direction]}, use ${scrollToSuggestion[direction]} instead.`);
+        }
         async screenshotBase64() {
             debugDevice('screenshotBase64 begin');
             const adapter = this.getScrcpyAdapter();
@@ -1437,58 +1456,66 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         async scrollUp(distance, startPoint) {
             const { height } = await this.size();
             const scrollDistance = Math.round(distance || height);
+            const hasExplicitDistance = void 0 !== distance;
             if (startPoint) {
                 const start = {
                     x: Math.round(startPoint.left),
                     y: Math.round(startPoint.top)
                 };
                 const end = this.calculateScrollEndPoint(start, 0, scrollDistance, 0, height);
+                if (hasExplicitDistance) this.warnScrollDistanceClamped('up', scrollDistance, Math.abs(end.y - start.y));
                 await this.mouseDrag(start, end);
                 return;
             }
-            await this.scroll(0, -scrollDistance);
+            await this.scroll(0, -scrollDistance, void 0, hasExplicitDistance, 'up');
         }
         async scrollDown(distance, startPoint) {
             const { height } = await this.size();
             const scrollDistance = Math.round(distance || height);
+            const hasExplicitDistance = void 0 !== distance;
             if (startPoint) {
                 const start = {
                     x: Math.round(startPoint.left),
                     y: Math.round(startPoint.top)
                 };
                 const end = this.calculateScrollEndPoint(start, 0, -scrollDistance, 0, height);
+                if (hasExplicitDistance) this.warnScrollDistanceClamped('down', scrollDistance, Math.abs(end.y - start.y));
                 await this.mouseDrag(start, end);
                 return;
             }
-            await this.scroll(0, scrollDistance);
+            await this.scroll(0, scrollDistance, void 0, hasExplicitDistance, 'down');
         }
         async scrollLeft(distance, startPoint) {
             const { width } = await this.size();
             const scrollDistance = Math.round(distance || width);
+            const hasExplicitDistance = void 0 !== distance;
             if (startPoint) {
                 const start = {
                     x: Math.round(startPoint.left),
                     y: Math.round(startPoint.top)
                 };
                 const end = this.calculateScrollEndPoint(start, scrollDistance, 0, width, 0);
+                if (hasExplicitDistance) this.warnScrollDistanceClamped('left', scrollDistance, Math.abs(end.x - start.x));
                 await this.mouseDrag(start, end);
                 return;
             }
-            await this.scroll(-scrollDistance, 0);
+            await this.scroll(-scrollDistance, 0, void 0, hasExplicitDistance, 'left');
         }
         async scrollRight(distance, startPoint) {
             const { width } = await this.size();
             const scrollDistance = Math.round(distance || width);
+            const hasExplicitDistance = void 0 !== distance;
             if (startPoint) {
                 const start = {
                     x: Math.round(startPoint.left),
                     y: Math.round(startPoint.top)
                 };
                 const end = this.calculateScrollEndPoint(start, -scrollDistance, 0, width, 0);
+                if (hasExplicitDistance) this.warnScrollDistanceClamped('right', scrollDistance, Math.abs(end.x - start.x));
                 await this.mouseDrag(start, end);
                 return;
             }
-            await this.scroll(scrollDistance, 0);
+            await this.scroll(scrollDistance, 0, void 0, hasExplicitDistance, 'right');
         }
         async ensureYadb() {
             if (!this.yadbPushed) {
@@ -1588,7 +1615,7 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
             const swipeDuration = duration ?? defaultNormalScrollDuration;
             await adb.shell(`input${this.getDisplayArg()} swipe ${fromX} ${fromY} ${toX} ${toY} ${swipeDuration}`);
         }
-        async scroll(deltaX, deltaY, duration) {
+        async scroll(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;
@@ -1598,8 +1625,15 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
             const maxNegativeDeltaX = width - startX;
             const maxPositiveDeltaY = startY;
             const maxNegativeDeltaY = height - startY;
+            const originalDeltaX = deltaX;
+            const originalDeltaY = deltaY;
             deltaX = Math.max(-maxNegativeDeltaX, Math.min(deltaX, maxPositiveDeltaX));
             deltaY = Math.max(-maxNegativeDeltaY, Math.min(deltaY, maxPositiveDeltaY));
+            if (warnOnClamp && direction && (deltaX !== originalDeltaX || deltaY !== originalDeltaY)) {
+                const requestedDistance = 'left' === direction || 'right' === direction ? Math.abs(originalDeltaX) : Math.abs(originalDeltaY);
+                const appliedDistance = 'left' === direction || 'right' === direction ? Math.abs(deltaX) : Math.abs(deltaY);
+                this.warnScrollDistanceClamped(direction, requestedDistance, appliedDistance);
+            }
             const endX = Math.round(startX - deltaX);
             const endY = Math.round(startY - deltaY);
             const { x: adjustedStartX, y: adjustedStartY } = await this.adjustCoordinates(startX, startY);
@@ -1756,7 +1790,7 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
                 }
                 debugDevice(`Keyboard still shown after keycode ${keyCode}, trying next key`);
             }
-            console.warn('Warning: Failed to hide the software keyboard after trying both ESC and BACK keys');
+            warnDevice('Warning: Failed to hide the software keyboard after trying both ESC and BACK keys');
             return false;
         }
         constructor(deviceId, options){
@@ -1986,7 +2020,7 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         constructor(toolsManager){
             super({
                 name: '@midscene/android-mcp',
-                version: "1.7.4",
+                version: "1.7.5-beta-20260418223706.0",
                 description: 'Control the Android device using natural language commands'
             }, toolsManager);
         }

package/dist/types/index.d.ts

@@ -168,6 +168,7 @@ export declare class AndroidDevice implements AbstractInterface {
      * @returns The calculated end point for the scroll gesture
      */
     private calculateScrollEndPoint;
+    private warnScrollDistanceClamped;
     screenshotBase64(): Promise<string>;
     clearInput(element?: ElementInfo): Promise<void>;
     forceScreenshot(path: string): Promise<void>;
@@ -206,7 +207,7 @@ export declare class AndroidDevice implements AbstractInterface {
         x: number;
         y: number;
     }, duration?: number): Promise<void>;
-    scroll(deltaX: number, deltaY: number, duration?: number): Promise<void>;
+    scroll(deltaX: number, deltaY: number, duration?: number, warnOnClamp?: boolean, direction?: ScrollDirection): Promise<void>;
     destroy(): Promise<void>;
     /**
      * Get the current time from the Android device.
@@ -445,6 +446,8 @@ declare interface ScrcpyScreenshotOptions {
     idleTimeoutMs?: number;
 }
 
+declare type ScrollDirection = 'up' | 'down' | 'left' | 'right';
+
 /**
  * Helper type to convert DeviceAction to wrapped method signature
  */

package/dist/types/mcp-server.d.ts

@@ -160,6 +160,7 @@ declare class AndroidDevice implements AbstractInterface {
      * @returns The calculated end point for the scroll gesture
      */
     private calculateScrollEndPoint;
+    private warnScrollDistanceClamped;
     screenshotBase64(): Promise<string>;
     clearInput(element?: ElementInfo): Promise<void>;
     forceScreenshot(path: string): Promise<void>;
@@ -198,7 +199,7 @@ declare class AndroidDevice implements AbstractInterface {
         x: number;
         y: number;
     }, duration?: number): Promise<void>;
-    scroll(deltaX: number, deltaY: number, duration?: number): Promise<void>;
+    scroll(deltaX: number, deltaY: number, duration?: number, warnOnClamp?: boolean, direction?: ScrollDirection): Promise<void>;
     destroy(): Promise<void>;
     /**
      * Get the current time from the Android device.
@@ -270,6 +271,8 @@ export declare function mcpServerForAgent(agent: Agent | AndroidAgent): {
     launchHttp(options: LaunchMCPServerOptions): Promise<LaunchMCPServerResult>;
 };
 
+declare type ScrollDirection = 'up' | 'down' | 'left' | 'right';
+
 /**
  * Helper type to convert DeviceAction to wrapped method signature
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@midscene/android",
-  "version": "1.7.4",
+  "version": "1.7.5-beta-20260418223706.0",
   "description": "Android automation library for Midscene",
   "keywords": [
     "Android UI automation",
@@ -41,8 +41,8 @@
     "@yume-chan/stream-extra": "2.1.0",
     "appium-adb": "12.12.1",
     "sharp": "^0.34.3",
-    "@midscene/shared": "1.7.4",
-    "@midscene/core": "1.7.4"
+    "@midscene/core": "1.7.5-beta-20260418223706.0",
+    "@midscene/shared": "1.7.5-beta-20260418223706.0"
   },
   "optionalDependencies": {
     "@ffmpeg-installer/ffmpeg": "^1.1.0"
@@ -51,12 +51,12 @@
     "@rslib/core": "^0.18.3",
     "@types/node": "^18.0.0",
     "dotenv": "^16.4.5",
-    "gh-release-fetch": "^4.0.3",
     "typescript": "^5.8.3",
     "tsx": "^4.19.2",
+    "undici": "^6.0.0",
     "vitest": "3.0.5",
     "zod": "^3.25.1",
-    "@midscene/playground": "1.7.4"
+    "@midscene/playground": "1.7.5-beta-20260418223706.0"
   },
   "license": "MIT",
   "scripts": {