@skrillex1224/android-toolkit 0.1.2 → 0.1.8

package/src/device.js

@@ -1,7 +1,10 @@
 import fs from 'node:fs';
+import zlib from 'node:zlib';
 import {execFile} from 'node:child_process';
 import {promisify} from 'node:util';
 
+import {Code} from './constants.js';
+import {CrawlerError} from './errors.js';
 import {Logger, sleep} from './logger.js';
 
 const execFileAsync = promisify(execFile);
@@ -14,35 +17,52 @@ export async function adbShell(ctx, args, options = {}) {
 
 export async function adbExec(ctx, args, options = {}) {
     // 执行原始 adb 命令；当云手机/TCP ADB 临时 offline 时，自动 adb connect 后重放一次。
+    const startedAt = Date.now();
+    Logger.debug('adb exec', {serial: ctx.serial, args: compactArgs(args), timeoutMs: Number(options.timeoutMs || 15000)});
     try {
         const {stdout} = await execFileAsync(ctx.adbPath, args, {
             timeout: Number(options.timeoutMs || 15000),
             maxBuffer: Number(options.maxBuffer || 12 * 1024 * 1024),
             encoding: options.encoding || 'utf8'
         });
+        Logger.debug('adb exec done', {serial: ctx.serial, duration: Logger.duration(startedAt)});
         return stdout;
     } catch (error) {
         // ADB over TCP 的云手机/云真机场景经常临时 offline。
         // 这里统一做一次 adb connect + 原命令重放，业务层不需要关心连接抖动。
-        if (!isAdbOfflineError(error) || !ctx.serial) throw error;
+        if (!isAdbOfflineError(error) || !ctx.serial) {
+            if (isAdbUnavailableError(error)) throw makeAdbUnavailableError(ctx, args, error);
+            Logger.warn('adb exec failed', {serial: ctx.serial, args: compactArgs(args), message: error?.message || String(error)});
+            throw error;
+        }
+        Logger.warn('adb offline, reconnecting', {serial: ctx.serial, args: compactArgs(args)});
         await execFileAsync(ctx.adbPath, ['connect', ctx.serial], {timeout: 15000}).catch(() => { });
         await sleep(1200);
-        const {stdout} = await execFileAsync(ctx.adbPath, args, {
-            timeout: Number(options.timeoutMs || 15000),
-            maxBuffer: Number(options.maxBuffer || 12 * 1024 * 1024),
-            encoding: options.encoding || 'utf8'
-        });
-        return stdout;
+        try {
+            const {stdout} = await execFileAsync(ctx.adbPath, args, {
+                timeout: Number(options.timeoutMs || 15000),
+                maxBuffer: Number(options.maxBuffer || 12 * 1024 * 1024),
+                encoding: options.encoding || 'utf8'
+            });
+            Logger.debug('adb exec retry done', {serial: ctx.serial, duration: Logger.duration(startedAt)});
+            return stdout;
+        } catch (retryError) {
+            if (isAdbUnavailableError(retryError)) throw makeAdbUnavailableError(ctx, args, retryError);
+            Logger.warn('adb exec retry failed', {serial: ctx.serial, args: compactArgs(args), message: retryError?.message || String(retryError)});
+            throw retryError;
+        }
     }
 }
 
 export async function forceStopApp(ctx, packageName = ctx.packageName) {
     // 强制关闭 App，用于每条任务开始前清理上一次页面状态。
+    Logger.info('force stop app', {serial: ctx.serial, packageName});
     await adbShell(ctx, ['am', 'force-stop', packageName]).catch(() => { });
 }
 
 export async function startActivity(ctx, component, args = []) {
     // 启动指定 Android Activity，component 形如 `com.tencent.mm/.ui.LauncherUI`。
+    Logger.info('start activity', {serial: ctx.serial, component});
     await adbShell(ctx, ['am', 'start', '-n', component, ...args]);
     await sleep(1800);
 }
@@ -55,11 +75,6 @@ export async function startLauncher(ctx, packageName = ctx.packageName, launcher
     ]);
 }
 
-export async function launchPackageByMonkey(ctx, packageName = ctx.packageName) {
-    // launcher 启动失败时的兜底：让 Android 自己找包的默认入口。
-    await adbShell(ctx, ['monkey', '-p', packageName, '1']);
-}
-
 export async function waitForForeground(ctx, packageName = ctx.packageName, timeoutMs = 6000) {
     // 轮询前台 Activity，直到目标包名进入前台或超时。
     const deadline = Date.now() + timeoutMs;
@@ -81,19 +96,24 @@ export async function screenSize(ctx) {
     };
 }
 
-export function px(ctx, ratio) {
-    // 把横向比例坐标转成屏幕像素。
-    return String(Math.floor((ctx.screen?.width || 720) * ratio));
+export async function screenDensity(ctx) {
+    const out = await adbShell(ctx, ['wm', 'density']).catch(() => '');
+    const match = /(\d+)/.exec(String(out || ''));
+    return match ? Number(match[1]) : 0;
 }
 
-export function py(ctx, ratio) {
-    // 把纵向比例坐标转成屏幕像素。
-    return String(Math.floor((ctx.screen?.height || 1280) * ratio));
+export async function overrideScreenSize(ctx, width, height) {
+    const safeWidth = Math.max(1, Math.round(Number(width) || 0));
+    const safeHeight = Math.max(1, Math.round(Number(height) || 0));
+    await adbShell(ctx, ['wm', 'size', `${safeWidth}x${safeHeight}`], {timeoutMs: 15000});
 }
 
-export async function tapRatio(ctx, x, y) {
-    // 点击比例坐标，适合不同分辨率设备共用同一套大致点位。
-    await adbInput(ctx, ['tap', px(ctx, x), py(ctx, y)]);
+export async function resetScreenSize(ctx) {
+    await adbShell(ctx, ['wm', 'size', 'reset'], {timeoutMs: 15000});
+}
+
+export async function resetScreenDensity(ctx) {
+    await adbShell(ctx, ['wm', 'density', 'reset'], {timeoutMs: 15000});
 }
 
 export async function tapAbsolute(ctx, x, y) {
@@ -116,11 +136,6 @@ export async function click(ctx, pointOrX, y) {
     return tapAbsolute(ctx, pointOrX, y);
 }
 
-export async function swipeRatio(ctx, fromX, fromY, toX, toY, durationMs = 500) {
-    // 使用比例坐标滑动，适合滚动列表、收起弹层等通用手势。
-    await adbInput(ctx, ['swipe', px(ctx, fromX), py(ctx, fromY), px(ctx, toX), py(ctx, toY), String(durationMs)]);
-}
-
 export async function move(ctx, from, to, durationMs = 500) {
     // ADB 没有鼠标 hover 概念，这里的 move 表示拖动/滑动手势。
     // from/to 使用屏幕绝对坐标，便于和截图/其他定位结果直接衔接。
@@ -139,35 +154,66 @@ export async function pressBack(ctx) {
     await adbInput(ctx, ['keyevent', 'BACK']).catch(() => { });
 }
 
-export async function pressEnter(ctx) {
-    // 发送 Android 回车键，常用于提交搜索框。
-    await adbInput(ctx, ['keyevent', 'ENTER']).catch(() => { });
+export async function dismissPermissionDialog(ctx) {
+    // Android 运行时权限弹窗会把原 App 的 Activity 压在下面。
+    // 这里只处理系统 permission controller：点击底部“拒绝”按钮区域，避免采集任务卡死。
+    const focused = await focusedActivity(ctx).catch(() => '');
+    if (!String(focused || '').includes('GrantPermissionsActivity')) return false;
+    const size = await screenSize(ctx);
+    await tapAbsolute(ctx, size.width * 0.50, size.height * 0.63).catch(() => { });
+    await sleep(1000);
+    return true;
 }
 
 export async function wakeAndUnlock(ctx) {
     // 唤醒并解锁设备。真机/云手机在息屏时 dumpsys 可能仍保留上一个 App，
     // 业务层会误判前台 Activity，所以每条原生任务开始前都应该先恢复可交互屏幕。
+    Logger.info('wake and unlock', {serial: ctx.serial});
     await adbInput(ctx, ['keyevent', 'KEYCODE_WAKEUP']).catch(() => { });
     await sleep(500);
     await adbInput(ctx, ['keyevent', 'MENU']).catch(() => { });
     await sleep(500);
-    await swipeRatio(ctx, 0.50, 0.82, 0.50, 0.25, 350).catch(() => { });
+    await swipeScreenRatio(ctx, 0.50, 0.82, 0.50, 0.25, 350).catch(() => { });
     await sleep(800);
 }
 
 export async function focusedActivity(ctx) {
+    // 优先从 activity manager 读取 resumed activity。`dumpsys window` 在微信 WebView
+    // 场景里可能同时保留旧窗口和新窗口，直接读 window focus 容易误判。
+    const resumed = await resumedActivity(ctx).catch(() => '');
+    if (resumed) return resumed;
+
     // 从 dumpsys window 中提取当前前台 Activity，用于替代 OCR 做页面状态判断。
     const out = await adbShell(ctx, ['dumpsys', 'window']);
     let fallback = '';
-    let focused = '';
+    let currentFocus = '';
+    let appWindowFocus = '';
     for (const line of String(out || '').split('\n')) {
-        if (line.includes('mCurrentFocus') || line.includes('mFocusedApp')) {
-            const trimmed = line.trim();
-            if (!fallback) fallback = trimmed;
-            if (!trimmed.includes('=null')) focused = trimmed;
-        }
+        const trimmed = line.trim();
+        if (!trimmed.includes('mCurrentFocus') && !trimmed.includes('mFocusedApp')) continue;
+        if (!fallback) fallback = trimmed;
+        if (trimmed.includes('=null')) continue;
+        // dumpsys window 里会同时出现当前窗口和历史 token 行。
+        // 只信真实窗口焦点和 AppWindowToken，避免把旧 LauncherUI Token 当成当前页。
+        if (trimmed.includes('mCurrentFocus=Window')) currentFocus = trimmed;
+        else if (trimmed.includes('mFocusedApp=AppWindowToken')) appWindowFocus = trimmed;
     }
-    return focused || fallback || String(out || '').trim();
+    return currentFocus || appWindowFocus || fallback || String(out || '').trim();
+}
+
+async function resumedActivity(ctx) {
+    const out = await adbShell(ctx, ['dumpsys', 'activity', 'activities'], {
+        timeoutMs: 15000,
+        maxBuffer: 12 * 1024 * 1024
+    });
+    let fallback = '';
+    for (const line of String(out || '').split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed.includes('ActivityRecord') || !trimmed.includes('/')) continue;
+        if (trimmed.includes('mTopResumedActivity') || trimmed.includes('topResumedActivity')) return trimmed;
+        if (trimmed.includes('mResumedActivity')) fallback = trimmed;
+    }
+    return fallback;
 }
 
 export function activityIncludes(focused, fragment) {
@@ -177,10 +223,15 @@ export function activityIncludes(focused, fragment) {
 
 export async function waitForActivity(ctx, predicate, timeoutMs = 15000, intervalMs = 700) {
     // 等待前台 Activity 满足调用方 predicate。
+    const startedAt = Date.now();
+    Logger.info('wait activity start', {serial: ctx.serial, timeoutMs, intervalMs});
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
         const focused = await focusedActivity(ctx).catch(() => '');
-        if (predicate(focused)) return focused;
+        if (predicate(focused)) {
+            Logger.info('wait activity matched', {serial: ctx.serial, duration: Logger.duration(startedAt), focused: summarizeText(focused, 160)});
+            return focused;
+        }
         await sleep(intervalMs);
     }
     throw new Error(`waitForActivity timeout: focused=${await focusedActivity(ctx).catch(() => '')}`);
@@ -188,25 +239,71 @@ export async function waitForActivity(ctx, predicate, timeoutMs = 15000, interva
 
 export async function screenshotBase64(ctx) {
     // 获取当前屏幕 PNG，并转成 base64 写入 dataset artifact。
-    const stdout = await adbExec(ctx, ['-s', ctx.serial, 'exec-out', 'screencap', '-p'], {
-        timeoutMs: 15000,
-        encoding: 'buffer',
-        maxBuffer: 8 * 1024 * 1024
-    });
+    const stdout = await screenshotPng(ctx);
     return Buffer.from(stdout).toString('base64');
 }
 
+export async function longScreenshotBase64(ctx, options = {}) {
+    const startedAt = Date.now();
+    const size = await screenSize(ctx).catch(() => ({width: 720, height: 1280}));
+    const captureCount = Math.max(1, Math.min(8, Number(options.captureCount || 4)));
+    const topCrop = clampInt(Number(options.topCrop ?? Math.floor(size.height * 0.12)), 0, size.height - 1);
+    const bottomCrop = clampInt(Number(options.bottomCrop ?? Math.floor(size.height * 0.18)), 0, size.height - topCrop - 1);
+    const swipeFromY = Number(options.swipeFromY || 0.78);
+    const swipeToY = Number(options.swipeToY || 0.28);
+    const swipeDurationMs = Number(options.swipeDurationMs || 650);
+    const settleMs = Number(options.settleMs || 900);
+    const scrollToTopFirst = Boolean(options.scrollToTopFirst);
+    const scrollToTopSwipes = Math.max(0, Math.min(8, Number(options.scrollToTopSwipes || 4)));
+    const pngs = [];
+
+    Logger.info('long screenshot start', {
+        serial: ctx.serial,
+        captureCount,
+        topCrop,
+        bottomCrop,
+        width: size.width,
+        height: size.height
+    });
+
+    if (scrollToTopFirst) {
+        for (let i = 0; i < scrollToTopSwipes; i += 1) {
+            await swipeScreenRatio(ctx, 0.50, swipeToY, 0.50, swipeFromY, swipeDurationMs).catch(() => { });
+            await sleep(Math.max(350, Math.floor(settleMs * 0.6)));
+        }
+    }
+
+    for (let i = 0; i < captureCount; i += 1) {
+        const png = await screenshotPng(ctx);
+        pngs.push(png);
+        if (i < captureCount - 1) {
+            await swipeScreenRatio(ctx, 0.50, swipeFromY, 0.50, swipeToY, swipeDurationMs).catch(() => { });
+            await sleep(settleMs);
+        }
+    }
+
+    const stitched = stitchVerticalPngs(pngs, {
+        topCrop,
+        bottomCrop,
+        maxOutputHeight: Math.max(size.height, Number(options.maxOutputHeight || size.height * captureCount)),
+        dedupeAdjacent: options.dedupeAdjacent !== false
+    });
+    Logger.info('long screenshot done', {
+        serial: ctx.serial,
+        duration: Logger.duration(startedAt),
+        bytes: stitched.length,
+        captureCount: pngs.length
+    });
+    return stitched.toString('base64');
+}
+
 export async function saveDebugScreenshot(ctx, name) {
     // 保存调试截图到 /tmp，主要用于本地定位点击点和页面状态。
     if (!ctx.serial) return '';
     const safeRunId = safeFilePart(ctx.runId || 'manual');
     const safeName = safeFilePart(name || 'screenshot');
     const out = `/tmp/android-toolkit-${safeRunId}-${safeName}.png`;
-    const stdout = await adbExec(ctx, ['-s', ctx.serial, 'exec-out', 'screencap', '-p'], {
-        timeoutMs: 15000,
-        encoding: 'buffer',
-        maxBuffer: 8 * 1024 * 1024
-    });
+    const stdout = await screenshotPng(ctx);
     fs.writeFileSync(out, stdout);
     Logger.info(`debug screenshot saved ${out}`);
     return out;
@@ -249,20 +346,309 @@ export async function type(ctx, text) {
 }
 
 async function adbInput(ctx, args, options = {}) {
-    // input tap/swipe/keyevent 在真机和云手机上偶发返回非 0，但重放同一条命令通常会成功。
-    // 这层只兜底设备输入抖动；页面级失败仍然交给业务 runStep/任务重试判断。
-    const retryTimes = Math.max(0, Number(options.retryTimes ?? 2));
-    let lastError = null;
-    for (let attempt = 0; attempt <= retryTimes; attempt += 1) {
-        try {
-            return await adbShell(ctx, ['input', ...args], options);
-        } catch (error) {
-            lastError = error;
-            if (attempt >= retryTimes || !isRetryableAdbInputError(error)) throw error;
-            await sleep(250 * (attempt + 1));
+    await adbShell(ctx, ['input', ...args], options);
+}
+
+export async function screenshotPng(ctx) {
+    return adbExec(ctx, ['-s', ctx.serial, 'exec-out', 'screencap', '-p'], {
+        timeoutMs: 15000,
+        encoding: 'buffer',
+        maxBuffer: 24 * 1024 * 1024
+    });
+}
+
+function stitchVerticalPngs(buffers, options = {}) {
+    const frames = buffers.map((buffer) => decodePng(buffer));
+    if (frames.length === 0) throw new Error('longScreenshotBase64 requires at least one screenshot');
+    const width = frames[0].width;
+    const colorType = frames[0].colorType;
+    const bitDepth = frames[0].bitDepth;
+    const bytesPerPixel = pngBytesPerPixel(colorType, bitDepth);
+    if (bytesPerPixel !== 4) {
+        throw new Error(`longScreenshotBase64 only supports RGBA PNG screenshots, got colorType=${colorType} bitDepth=${bitDepth}`);
+    }
+    for (const frame of frames) {
+        if (frame.width !== width || frame.colorType !== colorType || frame.bitDepth !== bitDepth) {
+            throw new Error('longScreenshotBase64 screenshots have inconsistent PNG formats');
+        }
+    }
+
+    const uniqueFrames = [];
+    for (const frame of frames) {
+        const previous = uniqueFrames[uniqueFrames.length - 1];
+        if (previous && isNearDuplicateFrame(previous, frame, width, bytesPerPixel)) {
+            break;
+        }
+        uniqueFrames.push(frame);
+    }
+
+    const parts = [];
+    let totalHeight = 0;
+    const topCrop = Math.max(0, Number(options.topCrop || 0));
+    const bottomCrop = Math.max(0, Number(options.bottomCrop || 0));
+    const maxOutputHeight = Math.max(1, Number(options.maxOutputHeight || Number.MAX_SAFE_INTEGER));
+    for (let i = 0; i < uniqueFrames.length; i += 1) {
+        const frame = uniqueFrames[i];
+        const cropTop = i === 0 ? 0 : Math.min(topCrop, frame.height - 1);
+        const cropBottom = i === uniqueFrames.length - 1 ? 0 : Math.min(bottomCrop, frame.height - cropTop - 1);
+        let slice = cropFrame(frame, cropTop, cropBottom, bytesPerPixel);
+        if (options.dedupeAdjacent !== false && parts.length > 0) {
+            slice = removeDuplicateOverlap(parts[parts.length - 1], slice, width, bytesPerPixel);
+        }
+        if (slice.height <= 0) continue;
+        if (totalHeight + slice.height > maxOutputHeight) {
+            slice = cropSliceHeight(slice, maxOutputHeight - totalHeight, width, bytesPerPixel);
         }
+        if (slice.height <= 0) break;
+        parts.push(slice);
+        totalHeight += slice.height;
+        if (totalHeight >= maxOutputHeight) break;
+    }
+
+    const rgba = Buffer.alloc(width * totalHeight * bytesPerPixel);
+    let y = 0;
+    for (const part of parts) {
+        part.rgba.copy(rgba, y * width * bytesPerPixel);
+        y += part.height;
+    }
+    return encodePng({width, height: totalHeight, rgba});
+}
+
+function isNearDuplicateFrame(previous, current, width, bytesPerPixel) {
+    if (previous.height !== current.height || previous.width !== current.width) return false;
+    const rowBytes = width * bytesPerPixel;
+    const top = Math.floor(current.height * 0.18);
+    const bottom = Math.floor(current.height * 0.82);
+    const start = top * rowBytes;
+    const end = Math.max(start, bottom * rowBytes);
+    const previousSlice = previous.rgba.subarray(start, end);
+    const currentSlice = current.rgba.subarray(start, end);
+    return meanAbsoluteRowDifference(previousSlice, currentSlice) < 1.5;
+}
+
+function cropFrame(frame, cropTop, cropBottom, bytesPerPixel) {
+    const widthBytes = frame.width * bytesPerPixel;
+    const height = Math.max(0, frame.height - cropTop - cropBottom);
+    const start = cropTop * widthBytes;
+    const end = start + height * widthBytes;
+    return {
+        width: frame.width,
+        height,
+        rgba: Buffer.from(frame.rgba.subarray(start, end))
+    };
+}
+
+function cropSliceHeight(slice, height, width, bytesPerPixel) {
+    const cleanHeight = Math.max(0, Math.min(slice.height, Number(height || 0)));
+    return {
+        width: slice.width,
+        height: cleanHeight,
+        rgba: Buffer.from(slice.rgba.subarray(0, cleanHeight * width * bytesPerPixel))
+    };
+}
+
+function removeDuplicateOverlap(previous, current, width, bytesPerPixel) {
+    if (!previous?.rgba?.length || !current?.rgba?.length) return current;
+    const rowBytes = width * bytesPerPixel;
+    const maxOverlap = Math.min(previous.height, current.height, Math.floor(current.height * 0.82));
+    let overlapRows = 0;
+    for (let rows = maxOverlap; rows >= 48; rows -= 8) {
+        if (sampledOverlapDifference(previous, current, rows, width, bytesPerPixel) < 5.0) {
+            overlapRows = rows;
+            break;
+        }
+    }
+    if (overlapRows <= 0) return current;
+    return {
+        width: current.width,
+        height: current.height - overlapRows,
+        rgba: Buffer.from(current.rgba.subarray(overlapRows * rowBytes))
+    };
+}
+
+function sampledOverlapDifference(previous, current, rows, width, bytesPerPixel) {
+    const rowBytes = width * bytesPerPixel;
+    const sampleRows = Math.min(28, rows);
+    const rowStep = Math.max(1, Math.floor(rows / sampleRows));
+    const xStart = Math.floor(width * 0.06);
+    const xEnd = Math.max(xStart + 1, Math.floor(width * 0.94));
+    const xStep = Math.max(1, Math.floor((xEnd - xStart) / 180));
+    let diff = 0;
+    let count = 0;
+    for (let y = 0; y < rows; y += rowStep) {
+        const previousRow = previous.height - rows + y;
+        const currentRow = y;
+        const previousBase = previousRow * rowBytes;
+        const currentBase = currentRow * rowBytes;
+        for (let x = xStart; x < xEnd; x += xStep) {
+            const offset = x * bytesPerPixel;
+            diff += Math.abs(previous.rgba[previousBase + offset] - current.rgba[currentBase + offset]);
+            diff += Math.abs(previous.rgba[previousBase + offset + 1] - current.rgba[currentBase + offset + 1]);
+            diff += Math.abs(previous.rgba[previousBase + offset + 2] - current.rgba[currentBase + offset + 2]);
+            count += 3;
+        }
+    }
+    return diff / Math.max(1, count);
+}
+
+function meanAbsoluteRowDifference(left, right) {
+    const len = Math.min(left.length, right.length);
+    if (len <= 0) return Number.POSITIVE_INFINITY;
+    let diff = 0;
+    const stride = Math.max(1, Math.floor(len / 20000));
+    let count = 0;
+    for (let i = 0; i < len; i += stride) {
+        diff += Math.abs(left[i] - right[i]);
+        count += 1;
+    }
+    return diff / Math.max(1, count);
+}
+
+function decodePng(buffer) {
+    const signature = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+    if (!Buffer.from(buffer).subarray(0, 8).equals(signature)) throw new Error('invalid PNG signature');
+    let offset = 8;
+    let width = 0;
+    let height = 0;
+    let bitDepth = 0;
+    let colorType = 0;
+    const idat = [];
+
+    while (offset + 12 <= buffer.length) {
+        const length = buffer.readUInt32BE(offset);
+        const type = buffer.subarray(offset + 4, offset + 8).toString('ascii');
+        const data = buffer.subarray(offset + 8, offset + 8 + length);
+        offset += 12 + length;
+        if (type === 'IHDR') {
+            width = data.readUInt32BE(0);
+            height = data.readUInt32BE(4);
+            bitDepth = data[8];
+            colorType = data[9];
+        } else if (type === 'IDAT') {
+            idat.push(data);
+        } else if (type === 'IEND') {
+            break;
+        }
+    }
+    if (!width || !height) throw new Error('invalid PNG IHDR');
+    const bytesPerPixel = pngBytesPerPixel(colorType, bitDepth);
+    const rowBytes = width * bytesPerPixel;
+    const inflated = zlib.inflateSync(Buffer.concat(idat));
+    const rgba = Buffer.alloc(rowBytes * height);
+    let src = 0;
+    let dst = 0;
+    let previous = Buffer.alloc(rowBytes);
+    for (let y = 0; y < height; y += 1) {
+        const filter = inflated[src++];
+        const row = Buffer.from(inflated.subarray(src, src + rowBytes));
+        src += rowBytes;
+        unfilterPngRow(row, previous, filter, bytesPerPixel);
+        row.copy(rgba, dst);
+        dst += rowBytes;
+        previous = row;
+    }
+    return {width, height, bitDepth, colorType, rgba};
+}
+
+function encodePng({width, height, rgba}) {
+    const rowBytes = width * 4;
+    const raw = Buffer.alloc((rowBytes + 1) * height);
+    for (let y = 0; y < height; y += 1) {
+        const rawOffset = y * (rowBytes + 1);
+        raw[rawOffset] = 0;
+        rgba.copy(raw, rawOffset + 1, y * rowBytes, (y + 1) * rowBytes);
+    }
+    const chunks = [
+        makePngChunk('IHDR', makeIhdr(width, height)),
+        makePngChunk('IDAT', zlib.deflateSync(raw, {level: 6})),
+        makePngChunk('IEND', Buffer.alloc(0))
+    ];
+    return Buffer.concat([
+        Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+        ...chunks
+    ]);
+}
+
+function makeIhdr(width, height) {
+    const data = Buffer.alloc(13);
+    data.writeUInt32BE(width, 0);
+    data.writeUInt32BE(height, 4);
+    data[8] = 8;
+    data[9] = 6;
+    data[10] = 0;
+    data[11] = 0;
+    data[12] = 0;
+    return data;
+}
+
+function makePngChunk(type, data) {
+    const typeBuffer = Buffer.from(type, 'ascii');
+    const length = Buffer.alloc(4);
+    length.writeUInt32BE(data.length, 0);
+    const crcBuffer = Buffer.alloc(4);
+    crcBuffer.writeUInt32BE(crc32(Buffer.concat([typeBuffer, data])), 0);
+    return Buffer.concat([length, typeBuffer, data, crcBuffer]);
+}
+
+function unfilterPngRow(row, previous, filter, bytesPerPixel) {
+    if (filter === 0) return;
+    for (let i = 0; i < row.length; i += 1) {
+        const left = i >= bytesPerPixel ? row[i - bytesPerPixel] : 0;
+        const up = previous[i] || 0;
+        const upLeft = i >= bytesPerPixel ? previous[i - bytesPerPixel] || 0 : 0;
+        let value = row[i];
+        if (filter === 1) value += left;
+        else if (filter === 2) value += up;
+        else if (filter === 3) value += Math.floor((left + up) / 2);
+        else if (filter === 4) value += paethPredictor(left, up, upLeft);
+        else throw new Error(`unsupported PNG filter ${filter}`);
+        row[i] = value & 0xff;
     }
-    throw lastError;
+}
+
+function pngBytesPerPixel(colorType, bitDepth) {
+    if (bitDepth !== 8) throw new Error(`unsupported PNG bitDepth ${bitDepth}`);
+    if (colorType === 6) return 4;
+    if (colorType === 2) return 3;
+    if (colorType === 0) return 1;
+    throw new Error(`unsupported PNG colorType ${colorType}`);
+}
+
+function paethPredictor(a, b, c) {
+    const p = a + b - c;
+    const pa = Math.abs(p - a);
+    const pb = Math.abs(p - b);
+    const pc = Math.abs(p - c);
+    if (pa <= pb && pa <= pc) return a;
+    if (pb <= pc) return b;
+    return c;
+}
+
+const CRC_TABLE = makeCrcTable();
+
+function crc32(buffer) {
+    let crc = 0xffffffff;
+    for (const byte of buffer) {
+        crc = CRC_TABLE[(crc ^ byte) & 0xff] ^ (crc >>> 8);
+    }
+    return (crc ^ 0xffffffff) >>> 0;
+}
+
+function makeCrcTable() {
+    const table = new Uint32Array(256);
+    for (let n = 0; n < 256; n += 1) {
+        let c = n;
+        for (let k = 0; k < 8; k += 1) {
+            c = (c & 1) ? (0xedb88320 ^ (c >>> 1)) : (c >>> 1);
+        }
+        table[n] = c >>> 0;
+    }
+    return table;
+}
+
+function clampInt(value, min, max) {
+    const clean = Number.isFinite(value) ? Math.trunc(value) : min;
+    return Math.max(min, Math.min(max, clean));
 }
 
 function isAdbOfflineError(error) {
@@ -270,12 +656,20 @@ function isAdbOfflineError(error) {
     return message.includes('device offline') || message.includes('device unauthorized');
 }
 
-function isRetryableAdbInputError(error) {
+function isAdbUnavailableError(error) {
     const message = String(error?.message || error || '').toLowerCase();
-    if (isAdbOfflineError(error)) return true;
-    if (message.includes('command failed:') && message.includes(' shell input ')) return true;
-    if (message.includes('closed') || message.includes('broken pipe') || message.includes('connection reset')) return true;
-    return false;
+    return message.includes('device not found') || message.includes('no devices/emulators found');
+}
+
+function makeAdbUnavailableError(ctx, args, error) {
+    return new CrawlerError({
+        message: `adb_unavailable: ${error?.message || String(error)}`,
+        code: Code.AdbUnavailable,
+        context: {
+            serial: ctx.serial,
+            args
+        }
+    });
 }
 
 function isBounds(value) {
@@ -287,6 +681,18 @@ function isBounds(value) {
     return [left, top, right, bottom].every(Number.isFinite) && right > left && bottom > top;
 }
 
+async function swipeScreenRatio(ctx, fromX, fromY, toX, toY, durationMs = 500) {
+    const size = await screenSize(ctx).catch(() => ({width: 720, height: 1280}));
+    await adbInput(ctx, [
+        'swipe',
+        String(Math.floor(size.width * fromX)),
+        String(Math.floor(size.height * fromY)),
+        String(Math.floor(size.width * toX)),
+        String(Math.floor(size.height * toY)),
+        String(durationMs)
+    ]);
+}
+
 function safeFilePart(value) {
     return String(value).replace(/[^a-zA-Z0-9_.-]+/g, '-');
 }
@@ -313,29 +719,40 @@ function adbInputTextForShell(raw) {
     return `''${escapedText}''`;
 }
 
+function compactArgs(args) {
+    return (args || []).map((arg) => summarizeText(arg, 80)).join(' ');
+}
+
+function summarizeText(value, maxLen) {
+    const text = String(value || '').replace(/\s+/g, ' ').trim();
+    if (text.length <= maxLen) return text;
+    return `${text.slice(0, maxLen)}...`;
+}
+
 export const Device = {
     adbShell,
     adbExec,
     forceStopApp,
     startActivity,
     startLauncher,
-    launchPackageByMonkey,
     waitForForeground,
     screenSize,
-    px,
-    py,
-    tapRatio,
+    screenDensity,
+    overrideScreenSize,
+    resetScreenSize,
+    resetScreenDensity,
     tapAbsolute,
     click,
-    swipeRatio,
     move,
     pressBack,
-    pressEnter,
+    dismissPermissionDialog,
     wakeAndUnlock,
     focusedActivity,
     activityIncludes,
     waitForActivity,
+    screenshotPng,
     screenshotBase64,
+    longScreenshotBase64,
     saveDebugScreenshot,
     clearInputByDelete,
     typeText,