@skrillex1224/android-toolkit 0.1.9 → 1.0.1

package/src/device.js

@@ -1,761 +0,0 @@
-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);
-
-export async function adbShell(ctx, args, options = {}) {
-    // 在指定设备上执行 `adb shell ...`，所有设备侧命令都从这里收口。
-    if (!ctx.serial) throw new Error('device.serial is empty');
-    return adbExec(ctx, ['-s', ctx.serial, 'shell', ...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) {
-            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);
-        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);
-}
-
-export async function startLauncher(ctx, packageName = ctx.packageName, launcherActivity = '.ui.LauncherUI') {
-    // 按 launcher 方式启动 App 首页；业务方只需要传包名和首页 Activity。
-    await startActivity(ctx, `${packageName}/${launcherActivity}`, [
-        '-a', 'android.intent.action.MAIN',
-        '-c', 'android.intent.category.LAUNCHER'
-    ]);
-}
-
-export async function waitForForeground(ctx, packageName = ctx.packageName, timeoutMs = 6000) {
-    // 轮询前台 Activity，直到目标包名进入前台或超时。
-    const deadline = Date.now() + timeoutMs;
-    while (Date.now() < deadline) {
-        const focused = await focusedActivity(ctx).catch(() => '');
-        if (focused.includes(packageName)) return true;
-        await sleep(500);
-    }
-    return false;
-}
-
-export async function screenSize(ctx) {
-    // 读取屏幕尺寸，失败时给一个常见竖屏默认值，避免后续坐标计算崩掉。
-    const out = await adbShell(ctx, ['wm', 'size']).catch(() => '');
-    const match = /(\d+)x(\d+)/.exec(String(out || ''));
-    return {
-        width: match ? Number(match[1]) : 720,
-        height: match ? Number(match[2]) : 1280
-    };
-}
-
-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 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 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) {
-    // 点击绝对像素坐标，适合已经从截图或 DOM rect 算出的精确点。
-    await adbInput(ctx, ['tap', String(Math.round(Number(x))), String(Math.round(Number(y)))]);
-}
-
-export async function click(ctx, pointOrX, y) {
-    // 对齐 Playwright 的直觉命名：业务代码可以写 Device.click(ctx, point)，
-    // 也可以直接传 View/DOM bounds。toolkit 统一判断点击中心点。
-    if (pointOrX && typeof pointOrX === 'object') {
-        if (isBounds(pointOrX)) {
-            return tapAbsolute(ctx, (Number(pointOrX.left) + Number(pointOrX.right)) / 2, (Number(pointOrX.top) + Number(pointOrX.bottom)) / 2);
-        }
-        if (isBounds(pointOrX.bounds)) {
-            return tapAbsolute(ctx, (Number(pointOrX.bounds.left) + Number(pointOrX.bounds.right)) / 2, (Number(pointOrX.bounds.top) + Number(pointOrX.bounds.bottom)) / 2);
-        }
-        return tapAbsolute(ctx, pointOrX.x, pointOrX.y);
-    }
-    return tapAbsolute(ctx, pointOrX, y);
-}
-
-export async function move(ctx, from, to, durationMs = 500) {
-    // ADB 没有鼠标 hover 概念，这里的 move 表示拖动/滑动手势。
-    // from/to 使用屏幕绝对坐标，便于和截图/其他定位结果直接衔接。
-    await adbInput(ctx, [
-        'swipe',
-        String(Math.round(Number(from?.x))),
-        String(Math.round(Number(from?.y))),
-        String(Math.round(Number(to?.x))),
-        String(Math.round(Number(to?.y))),
-        String(durationMs)
-    ]);
-}
-
-export async function pressBack(ctx) {
-    // 发送 Android 返回键。
-    await adbInput(ctx, ['keyevent', 'BACK']).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 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 currentFocus = '';
-    let appWindowFocus = '';
-    for (const line of String(out || '').split('\n')) {
-        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 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) {
-    // 小工具：判断当前 Activity 文本是否包含目标片段。
-    return String(focused || '').includes(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)) {
-            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(() => '')}`);
-}
-
-export async function screenshotBase64(ctx) {
-    // 获取当前屏幕 PNG，并转成 base64 写入 dataset artifact。
-    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 screenshotPng(ctx);
-    fs.writeFileSync(out, stdout);
-    Logger.info(`debug screenshot saved ${out}`);
-    return out;
-}
-
-export async function clearInputByDelete(ctx, count = 40) {
-    // 先把光标移到文本末尾再删除。微信搜索框里如果光标停在中间，
-    // 直接 DEL 会只删前半段，留下旧 query 尾巴污染下一次搜索。
-    await adbInput(ctx, ['keyevent', 'KEYCODE_MOVE_END']).catch(() => { });
-    await sleep(150);
-    for (let i = 0; i < count; i += 1) {
-        await adbInput(ctx, ['keyevent', 'DEL']).catch(() => { });
-    }
-}
-
-export async function typeText(ctx, text) {
-    // 输入中文文本。要求设备安装 Appium Settings，因为原生 adb input text 不支持可靠中文。
-    const value = String(text || '');
-    if (!value) return;
-    const unicodeIME = 'io.appium.settings/.UnicodeIME';
-    const previousIME = String(await adbShell(ctx, ['settings', 'get', 'secure', 'default_input_method']).catch(() => '')).trim();
-    try {
-        // 中文输入统一走 Appium Settings UnicodeIME 思路：
-        // 普通 `adb input text` 会把中文打成乱码；IMAP UTF-7 编码可以让 UnicodeIME
-        // 在 Android 输入法层还原真实中文，适用于任意支持 ADB 的真机/云手机。
-        await adbShell(ctx, ['ime', 'enable', unicodeIME]).catch(() => { });
-        await adbShell(ctx, ['ime', 'set', unicodeIME]);
-        await sleep(800);
-        await adbInput(ctx, ['text', adbInputTextForShell(imapUtf7Encode(value))]);
-        await sleep(1200);
-    } finally {
-        if (previousIME && previousIME !== 'null' && previousIME !== unicodeIME) {
-            await adbShell(ctx, ['ime', 'set', previousIME]).catch(() => { });
-        }
-    }
-}
-
-export async function type(ctx, text) {
-    return typeText(ctx, text);
-}
-
-async function adbInput(ctx, args, options = {}) {
-    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;
-    }
-}
-
-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) {
-    const message = String(error?.message || error || '').toLowerCase();
-    return message.includes('device offline') || message.includes('device unauthorized');
-}
-
-function isAdbUnavailableError(error) {
-    const message = String(error?.message || error || '').toLowerCase();
-    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) {
-    if (!value || typeof value !== 'object') return false;
-    const left = Number(value.left);
-    const top = Number(value.top);
-    const right = Number(value.right);
-    const bottom = Number(value.bottom);
-    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, '-');
-}
-
-function imapUtf7Encode(value) {
-    return String(value || '')
-        .replace(/&/g, '&-')
-        .replace(/[^\x20-\x7e]+/g, (chunk) => `&${utf7EncodeChunk(chunk).replace(/\//g, ',')}-`);
-}
-
-function utf7EncodeChunk(value) {
-    const buffer = Buffer.alloc(String(value).length * 2, 'ascii');
-    let offset = 0;
-    for (let i = 0; i < String(value).length; i += 1) {
-        const code = String(value).charCodeAt(i);
-        buffer[offset++] = code >> 8;
-        buffer[offset++] = code & 0xff;
-    }
-    return buffer.toString('base64').replace(/=+$/, '');
-}
-
-function adbInputTextForShell(raw) {
-    const escapedText = String(raw || '').replace(/[()<>|;&*\\~^"'$`]/g, '\\$&').replace(/ /g, '%s');
-    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,
-    waitForForeground,
-    screenSize,
-    screenDensity,
-    overrideScreenSize,
-    resetScreenSize,
-    resetScreenDensity,
-    tapAbsolute,
-    click,
-    move,
-    pressBack,
-    dismissPermissionDialog,
-    wakeAndUnlock,
-    focusedActivity,
-    activityIncludes,
-    waitForActivity,
-    screenshotPng,
-    screenshotBase64,
-    longScreenshotBase64,
-    saveDebugScreenshot,
-    clearInputByDelete,
-    typeText,
-    type,
-    sleep
-};