@flxapps/adbax 0.0.0-stage → 0.1.0

package/src/commands/screen.js

@@ -0,0 +1,112 @@
+// SPDX-License-Identifier: Apache-2.0
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { match } from '../select.js';
+import { kind, label, shortId } from '../tree.js';
+import { cachePath, fail } from '../util.js';
+import { selectorOptions, showUi } from './common.js';
+
+export async function ui(ctx) {
+  await showUi(ctx);
+}
+
+export async function find(ctx) {
+  const q = ctx.pos.join(' ') || fail('usage: adbax find <text>');
+  const dev = await ctx.device();
+  const nodes = await dev.tree();
+  const hits = match(nodes, q, { regex: !!ctx.flags.re });
+  if (!hits.length) fail(`no match for ${JSON.stringify(q)} on ${await dev.where()}`, 2);
+  const rows = dev.saveRows(nodes, !!ctx.flags.all);
+  for (const n of hits) {
+    const idx = rows.indexOf(n);
+    const id = shortId(n);
+    ctx.out(`${idx > -1 ? `[${idx}]` : '[-]'}  ${kind(n).padEnd(6)}  ${JSON.stringify(label(n))}  ${id ? `id=${id}  ` : ''}` +
+      `cls=${n.cls}  @${n.cx},${n.cy}  ${n.w}x${n.h}${n.enabled ? '' : '  !disabled'}`);
+  }
+}
+
+export async function inspect(ctx) {
+  const q = ctx.pos.join(' ') || fail('usage: adbax inspect <query>');
+  const dev = await ctx.device();
+  const nodes = await dev.tree();
+  const opts = selectorOptions(ctx.flags);
+  const hits = match(nodes, q, { regex: opts.regex });
+  const n = hits[opts.nth !== undefined ? +opts.nth : 0] || fail(`no node matching ${JSON.stringify(q)}`, 2);
+  ctx.out(JSON.stringify({
+    class: n.fullCls, text: n.text, 'content-desc': n.desc, hint: n.hint, 'resource-id': n.id, package: n.pkg,
+    bounds: `[${n.x1},${n.y1}][${n.x2},${n.y2}]`, center: [n.cx, n.cy], size: [n.w, n.h],
+    clickable: n.clickable, longClickable: n.longClickable, editable: n.editable, checkable: n.checkable,
+    checked: n.checked, scrollable: n.scrollable, enabled: n.enabled, focused: n.focused,
+    focusable: n.focusable, password: n.password,
+  }, null, 2));
+  const chain = [];
+  for (let a = n.parent; a; a = a.parent) {
+    chain.unshift(a.cls + (shortId(a) ? '#' + shortId(a) : '') + (a.clickable ? '(clickable)' : ''));
+  }
+  ctx.out('ancestors: ' + chain.join(' > '));
+  if (hits.length > 1) ctx.out(`(${hits.length} matches; --nth N picks another)`);
+}
+
+export async function current(ctx) {
+  const dev = await ctx.device();
+  ctx.out(await dev.where());
+  const a = (await dev.adb.shell("dumpsys activity activities 2>/dev/null | grep -m1 'ResumedActivity'", { soft: true })).trim();
+  if (a) ctx.out(a);
+}
+
+/** Resizes or converts on the host where the device could not; only macOS has a tool for it built in. */
+function convertOnHost(file, { width, jpeg }) {
+  if (process.platform !== 'darwin') return false;
+  const args = [];
+  if (width) args.push('--resampleWidth', String(width));
+  if (jpeg) args.push('-s', 'format', 'jpeg');
+  try {
+    execFileSync('sips', [...args, file, '--out', file], { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Writes a screenshot. Prints the path on stdout and the image size on stderr;
+ * `tap x,y --shot` later takes coordinates in this image's pixels.
+ */
+export async function screenshot(ctx) {
+  const { flags } = ctx;
+  const dev = await ctx.device();
+  let dest = path.resolve(ctx.pos[0] || cachePath(flags.small || flags.grid ? 'shot.jpg' : 'shot.png'));
+  const width = +(flags.width || flags.scale || 0) || (flags.small || flags.grid ? 540 : 0);
+  const grid = flags.grid ? (flags.grid === true ? Math.round((width || 540) / 6) : +flags.grid) : 0;
+  const jpeg = /\.jpe?g$/i.test(dest);
+  const shot = await dev.screenshot({ width, grid, format: jpeg ? 'jpeg' : 'png', quality: +(flags.quality || 80) });
+  fs.writeFileSync(dest, shot.data);
+  if (grid && !shot.scaled) process.stderr.write('adbax: --grid needs the on-device server; saved without it\n');
+  const device = shot.screenWidth ? { width: shot.screenWidth, height: shot.screenHeight } : await dev.screenSize();
+  let w = shot.width || (width || device.width);
+  if (!shot.scaled && (width || jpeg) && !convertOnHost(dest, { width, jpeg })) {
+    if (jpeg) {
+      const png = dest.replace(/\.jpe?g$/i, '.png');
+      fs.renameSync(dest, png);
+      dest = png;
+    }
+    w = device.width;
+    process.stderr.write('adbax: no on-device server and no host image tool; kept the full-size PNG\n');
+  }
+  const h = shot.height || Math.round(device.height * w / device.width);
+  dev.saveShot({ width: w, height: h, deviceWidth: device.width, deviceHeight: device.height });
+  ctx.out(dest);
+  if (w !== device.width) process.stderr.write(`${w}x${h} of ${device.width}x${device.height}: tap x,y --shot takes these pixels\n`);
+}
+
+export async function record(ctx) {
+  const dev = await ctx.device();
+  const secs = Math.min(+(ctx.pos[0] || 15), 180);
+  const dest = path.resolve(ctx.pos[1] || cachePath('rec.mp4'));
+  process.stderr.write(`recording ${secs}s ...\n`);
+  await dev.adb.shell(`screenrecord --time-limit ${secs} --bit-rate 4000000 /sdcard/adbax-rec.mp4`, { timeout: (secs + 30) * 1000 });
+  await dev.adb.run(['pull', '/sdcard/adbax-rec.mp4', dest], { soft: true });
+  await dev.adb.shell('rm -f /sdcard/adbax-rec.mp4', { soft: true });
+  ctx.out(dest);
+}

package/src/commands/server.js

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: Apache-2.0
+import { idleSeconds } from '../backends/server.js';
+import { fail } from '../util.js';
+
+/** adbax server [status|start|stop|restart|log] */
+export async function server(ctx) {
+  const sub = ctx.pos[0] || 'status';
+  const dev = await ctx.device();
+  const s = dev.server;
+  switch (sub) {
+    case 'status': {
+      const st = await s.status();
+      if (!st.running) {
+        return ctx.out(st.pid ? `pid ${st.pid} is up but not answering on a forward; \`adbax server restart\`` : 'not running');
+      }
+      const p = st.ping;
+      return ctx.out(`running: pid ${p.pid}, sdk ${p.sdk}, up ${Math.round(p.uptimeMs / 1000)}s, port ${st.port}` +
+        (st.current ? '' : ', older build (replaced on next use)'));
+    }
+    case 'start':
+    case 'restart': {
+      if (sub === 'restart') await s.stop();
+      const head = await s.start({ idle: +(ctx.flags.idle || idleSeconds()), force: true });
+      return ctx.out(`started: pid ${head.pid}, sdk ${head.sdk}, exits after ${ctx.flags.idle || idleSeconds()}s idle`);
+    }
+    case 'stop':
+      await s.stop();
+      return ctx.out('stopped');
+    case 'log':
+      return ctx.out((await s.log()).trim() || '(no log)');
+    default:
+      fail('usage: adbax server [status|start|stop|restart|log] [--idle seconds]');
+  }
+}

package/src/commands/system.js

@@ -0,0 +1,102 @@
+// SPDX-License-Identifier: Apache-2.0
+/* Logs, device settings for screenshots, and raw adb passthrough. */
+import { fail, q } from '../util.js';
+
+export async function log(ctx) {
+  const { flags } = ctx;
+  const pkg = ctx.pos[0];
+  const dev = await ctx.device();
+  const args = ['logcat', '-d', '-v', 'brief', '-t', String(flags.lines || 200)];
+  if (pkg) {
+    const pid = (await dev.adb.shell(`pidof ${q(pkg)}`, { soft: true })).trim().split(/\s+/)[0];
+    if (!pid) fail(`${pkg} is not running (no pid). Start it first, or drop the package argument.`);
+    args.push('--pid=' + pid);
+  }
+  if (flags.level) args.push('*:' + String(flags.level).toUpperCase());
+  let out = await dev.adb.run(args, { soft: true });
+  if (flags.grep) {
+    const re = new RegExp(String(flags.grep), 'i');
+    out = out.split('\n').filter((l) => re.test(l)).join('\n');
+  }
+  ctx.out(out.trim());
+}
+
+export async function crash(ctx) {
+  const dev = await ctx.device();
+  const out = (await dev.adb.run(['logcat', '-b', 'crash', '-d', '-t', String(ctx.flags.lines || 120)], { soft: true })).trim();
+  ctx.out(out || '(crash buffer empty)');
+}
+
+export async function clearlog(ctx) {
+  const dev = await ctx.device();
+  await dev.adb.run(['logcat', '-c'], { soft: true });
+  await dev.adb.run(['logcat', '-b', 'crash', '-c'], { soft: true });
+  ctx.out('log buffers cleared');
+}
+
+export async function dark(ctx) {
+  const on = ctx.pos[0] !== 'off';
+  await (await ctx.device()).adb.shell(`cmd uimode night ${on ? 'yes' : 'no'}`);
+  ctx.out('dark mode ' + (on ? 'on' : 'off'));
+}
+
+export async function font(ctx) {
+  const s = ctx.pos[0] || fail('usage: adbax font <0.85|1.0|1.3|2.0>');
+  if (!/^\d+(\.\d+)?$/.test(s)) fail('font: a scale like 1.0 or 1.3');
+  await (await ctx.device()).adb.shell(`settings put system font_scale ${s}`);
+  ctx.out('font_scale ' + s);
+}
+
+export async function anim(ctx) {
+  const on = ctx.pos[0] !== 'off';
+  const dev = await ctx.device();
+  const v = on ? '1.0' : '0.0';
+  await dev.adb.shell(['window_animation_scale', 'transition_animation_scale', 'animator_duration_scale']
+    .map((k) => `settings put global ${k} ${v}`).join('; '));
+  ctx.out('animations ' + (on ? 'on' : 'off'));
+}
+
+export async function rotate(ctx) {
+  const d = ctx.pos[0] || fail('usage: adbax rotate <0|90|180|270|auto>');
+  const dev = await ctx.device();
+  if (d === 'auto') {
+    await dev.adb.shell('settings put system accelerometer_rotation 1');
+    return ctx.out('rotation: auto');
+  }
+  const r = { 0: 0, 90: 1, 180: 2, 270: 3 }[d];
+  if (r === undefined) fail('rotate: 0, 90, 180, 270 or auto');
+  await dev.adb.shell(`settings put system accelerometer_rotation 0; settings put system user_rotation ${r}`);
+  ctx.out('rotation ' + d);
+}
+
+/** SystemUI demo mode: a clean status bar for store screenshots. */
+export async function demo(ctx) {
+  const on = ctx.pos[0] !== 'off';
+  const dev = await ctx.device();
+  const b = (extras) => `am broadcast -a com.android.systemui.demo ${extras}`;
+  if (!on) {
+    await dev.adb.shell(b('-e command exit'), { soft: true });
+    return ctx.out('demo mode off');
+  }
+  await dev.adb.shell(['settings put global sysui_demo_allowed 1',
+    b('-e command enter'),
+    b('-e command clock -e hhmm 1000'),
+    b('-e command battery -e level 100 -e plugged false'),
+    b('-e command network -e wifi show -e level 4'),
+    b('-e command network -e mobile show -e datatype none -e level 4'),
+    b('-e command notifications -e visible false')].join(' >/dev/null; '), { soft: true });
+  ctx.out('demo mode on (clean status bar for store screenshots)');
+}
+
+export async function shell(ctx) {
+  if (!ctx.pos.length) fail('usage: adbax shell <command>');
+  ctx.out((await (await ctx.device()).adb.shell(ctx.pos.join(' '))).trim());
+}
+
+export async function pull(ctx) {
+  ctx.out((await (await ctx.device()).adb.run(['pull', ...ctx.pos])).trim());
+}
+
+export async function push(ctx) {
+  ctx.out((await (await ctx.device()).adb.run(['push', ...ctx.pos])).trim());
+}

package/src/commands/touch.js

@@ -0,0 +1,210 @@
+// SPDX-License-Identifier: Apache-2.0
+import { describe, match, resolve, tappableAncestor } from '../select.js';
+import { tappable } from '../tree.js';
+import { delay, fail } from '../util.js';
+import { KEYS, maybeUi, selectorOptions, selectorSource } from './common.js';
+
+/** Screen pixels for x,y given with --shot, i.e. in the last screenshot's pixels. */
+function shotPoint(dev, x, y) {
+  return dev.fromShot(x, y) || fail('--shot: no screenshot taken yet on this device');
+}
+
+async function target(ctx, usage) {
+  const sel = ctx.pos.join(' ') || fail(usage);
+  const dev = await ctx.device();
+  const r = await resolve(sel, selectorSource(dev), { forTap: true, ...selectorOptions(ctx.flags) });
+  if (ctx.flags.shot) {
+    if (r.how !== 'coords') fail('--shot only applies to x,y coordinates');
+    const [x, y] = shotPoint(dev, r.x, r.y);
+    return { dev, r: { x, y, how: `shot ${r.x},${r.y}` } };
+  }
+  return { dev, r };
+}
+
+export async function tap(ctx) {
+  const { dev, r } = await target(ctx, 'usage: adbax tap <text|index|x,y>');
+  await dev.tap(r.x, r.y);
+  ctx.out(`tapped ${r.how} @${r.x},${r.y}`);
+  await maybeUi(ctx);
+}
+
+export async function longpress(ctx) {
+  const { dev, r } = await target(ctx, 'usage: adbax longpress <text|index|x,y> [--dur ms]');
+  await dev.swipe(r.x, r.y, r.x, r.y, +(ctx.flags.dur || 900));
+  ctx.out(`long-pressed ${r.how} @${r.x},${r.y}`);
+  await maybeUi(ctx);
+}
+
+export async function type(ctx) {
+  const { flags } = ctx;
+  const text = ctx.pos.join(' ');
+  if (!text && !flags.clear && !flags.set) fail('usage: adbax type <text> [--into <field>] [--clear | --set] [--enter]');
+  const dev = await ctx.device();
+  let existing = 0;
+  if (flags.into) {
+    const r = await resolve(String(flags.into), selectorSource(dev), { forTap: true, ...selectorOptions(flags) });
+    existing = ((r.node && r.node.text) || '').length;
+    await dev.tap(r.x, r.y);
+    // Tapping a field often starts a new activity; typing before the field
+    // has focus loses the first characters into the outgoing window.
+    if (!(await dev.waitForInput(3000))) await delay(600);
+    ctx.out(`focused ${r.how}`);
+  }
+  if (flags.set) {
+    // The whole field in one ACTION_SET_TEXT: no keystrokes, nothing left over from what
+    // was there, and no IME in between. For long values, where typing over a selection
+    // races the field's own state.
+    const now = await dev.setText(text);
+    if (now === null) fail('adbax: no editable field has focus; tap it first or use --into');
+    ctx.out(`set ${JSON.stringify(text)}` + (now !== text ? `  field reads ${JSON.stringify(now)}` : ''));
+    return;
+  }
+  if (flags.clear) await dev.clear(existing);
+  let via = '';
+  if (text) {
+    if (!(await dev.fast()) && /[^\x00-\x7F]/.test(text)) {
+      process.stderr.write('adbax: `input text` drops non-ASCII on most builds; check the field.\n');
+    }
+    via = (await dev.type(text)).via;
+  }
+  if (flags.enter) await dev.key([66]);
+  ctx.out(`typed ${JSON.stringify(text)}` + (via === 'settext' ? ' (set as field text, not keystrokes)' : '') +
+    (flags.enter ? ' + enter' : ''));
+  if (text && !flags.enter && !flags['no-verify']) {
+    await delay((await dev.fast()) ? 100 : 400);
+    const f = await dev.focus();
+    if (f && f.focused && f.text && f.text !== text && !f.password) {
+      ctx.out(`  field now reads ${JSON.stringify(f.text)}` + (f.text.length < text.length ? '  <- short, retry with --clear' : ''));
+    }
+  }
+  await maybeUi(ctx);
+}
+
+export async function key(ctx) {
+  if (!ctx.pos.length) fail(`usage: adbax key <name|number|KEYCODE_*>...   (${Object.keys(KEYS).join(' ')})`);
+  const codes = ctx.pos.map((k) => {
+    const lk = k.toLowerCase();
+    if (KEYS[lk] !== undefined) return KEYS[lk];
+    if (/^\d+$/.test(k)) return +k;
+    if (/^KEYCODE_\w+$/i.test(k)) return k.toUpperCase();
+    return fail('unknown key: ' + k);
+  });
+  const dev = await ctx.device();
+  await dev.key(codes, { long: !!ctx.flags.long });
+  ctx.out('key ' + ctx.pos.join(' '));
+  await maybeUi(ctx);
+}
+
+function namedKey(code, name) {
+  return async (ctx) => {
+    await (await ctx.device()).key([code]);
+    ctx.out(name);
+    await maybeUi(ctx);
+  };
+}
+export const back = namedKey(4, 'back');
+
+/**
+ * Closes the soft keyboard if one is showing, and does nothing otherwise. A bare
+ * `adbax back` closes the keyboard when it is up and leaves the screen when it is not,
+ * which turns a "hide the keyboard" step into a navigation bug.
+ */
+export async function hideKeyboard(ctx) {
+  const dev = await ctx.device();
+  if (await dev.keyboardUp()) {
+    await dev.key([4]);
+    ctx.out('keyboard hidden');
+  } else {
+    ctx.out('no keyboard');
+  }
+  await maybeUi(ctx);
+}
+export const home = namedKey(3, 'home');
+export const recents = namedKey(187, 'recents');
+
+export async function swipe(ctx) {
+  const { flags } = ctx;
+  const a = ctx.pos[0] || fail('usage: adbax swipe <up|down|left|right|x1,y1,x2,y2> [--dur ms] [--in <sel>]');
+  const dur = +(flags.dur || 300);
+  const dev = await ctx.device();
+  let pts;
+  if (a.split(',').length === 4) {
+    pts = a.split(',').map((v) => +v.trim());
+    if (flags.shot) pts = [...shotPoint(dev, pts[0], pts[1]), ...shotPoint(dev, pts[2], pts[3])];
+  } else if (!['up', 'down', 'left', 'right'].includes(a)) {
+    fail(`swipe: ${a}? Use up, down, left, right or x1,y1,x2,y2.`);
+  } else if (flags.in) {
+    const n = match(await dev.tree(), String(flags.in), { regex: !!flags.re })[0] || fail(`no node for --in ${flags.in}`);
+    const mx = n.cx;
+    const my = n.cy;
+    const padY = Math.round(n.h * 0.2);
+    const padX = Math.round(n.w * 0.15);
+    pts = { up: [mx, n.y2 - padY, mx, n.y1 + padY], down: [mx, n.y1 + padY, mx, n.y2 - padY],
+      left: [n.x2 - padX, my, n.x1 + padX, my], right: [n.x1 + padX, my, n.x2 - padX, my] }[a];
+  } else {
+    const { width: W, height: H } = await dev.screenSize();
+    // "swipe up" is the finger going up, i.e. scrolling down the content.
+    const r = Math.round;
+    pts = { up: [r(W / 2), r(H * 0.75), r(W / 2), r(H * 0.28)], down: [r(W / 2), r(H * 0.28), r(W / 2), r(H * 0.75)],
+      left: [r(W * 0.85), r(H / 2), r(W * 0.15), r(H / 2)], right: [r(W * 0.15), r(H / 2), r(W * 0.85), r(H / 2)] }[a];
+  }
+  await dev.swipe(...pts, dur);
+  ctx.out(`swipe ${pts.join(' ')} ${dur}`);
+  await maybeUi(ctx);
+}
+
+export async function scrollTo(ctx) {
+  const { flags } = ctx;
+  const q = ctx.pos.join(' ') || fail('usage: adbax scroll-to <text> [--max 12] [--dir up|down] [--tap]');
+  const max = +(flags.max || 12);
+  const contentUp = flags.dir === 'up';
+  const dev = await ctx.device();
+  for (let i = 0; i <= max; i++) {
+    const nodes = await dev.tree({ afterAction: i > 0 });
+    const hits = match(nodes, q, { regex: !!flags.re });
+    if (hits.length) {
+      dev.saveRows(nodes);
+      const n = hits[0];
+      ctx.out(`found after ${i} swipe(s): ${describe(n)} @${n.cx},${n.cy}`);
+      if (flags.tap) {
+        const t = tappable(n) ? n : tappableAncestor(n);
+        await dev.tap(t.cx, t.cy);
+        ctx.out(`tapped it @${t.cx},${t.cy}`);
+      }
+      return maybeUi(ctx);
+    }
+    if (i === max) break;
+    const sc = nodes.filter((n) => n.scrollable && n.h > 200).sort((a, b) => b.h * b.w - a.h * a.w)[0];
+    let x, top, bottom;
+    if (sc) {
+      const pad = Math.round(sc.h * 0.2);
+      [x, top, bottom] = [sc.cx, sc.y1 + pad, sc.y2 - pad];
+    } else {
+      const { width: W, height: H } = await dev.screenSize();
+      [x, top, bottom] = [Math.round(W / 2), Math.round(H * 0.28), Math.round(H * 0.75)];
+    }
+    if (contentUp) await dev.swipe(x, top, x, bottom, 250);
+    else await dev.swipe(x, bottom, x, top, 250);
+  }
+  fail(`${JSON.stringify(q)} not found after ${max} swipes on ${await dev.where()}`, 2);
+}
+
+export async function wait(ctx) {
+  const { flags } = ctx;
+  const q = ctx.pos.join(' ') || fail('usage: adbax wait <text> [--timeout 15] [--gone]');
+  const dev = await ctx.device();
+  const deadline = Date.now() + +(flags.timeout || 15) * 1000;
+  const interval = await dev.pollInterval();
+  while (Date.now() < deadline) {
+    const nodes = await dev.tree();
+    const hits = match(nodes, q, { regex: !!flags.re });
+    if (flags.gone ? !hits.length : hits.length) {
+      dev.saveRows(nodes);
+      if (hits.length) ctx.out(`ready: ${describe(hits[0])} @${hits[0].cx},${hits[0].cy}`);
+      else ctx.out(`gone: ${JSON.stringify(q)}`);
+      return maybeUi(ctx);
+    }
+    await delay(interval);
+  }
+  fail(`timed out waiting for ${JSON.stringify(q)}${flags.gone ? ' to disappear' : ''} on ${await dev.where()}`, 2);
+}

package/src/device.js

@@ -0,0 +1,197 @@
+// SPDX-License-Identifier: Apache-2.0
+import { Adb } from './adb.js';
+import { ServerBackend, ServerUnavailable } from './backends/server.js';
+import { ShellBackend } from './backends/shell.js';
+import { interesting, parseTree, rowRecord, screenInfo } from './tree.js';
+import { cachePath, delay, readJson, serialKey, writeJson } from './util.js';
+
+/**
+ * One device, and the backend that talks to it: the on-device server when it
+ * runs there, `adb shell` otherwise. Commands go through this and never pick a
+ * backend themselves.
+ */
+export class Device {
+  constructor(serial, { server = true, settle } = {}) {
+    this.serial = serial;
+    this.adb = new Adb(serial);
+    this.server = new ServerBackend(this.adb);
+    this.shell = new ShellBackend(this.adb);
+    this.useServer = server;
+    this.settle = settle;
+    this.chosen = null;
+  }
+
+  async backend() {
+    if (this.chosen) return this.chosen;
+    if (this.useServer) {
+      try {
+        await this.server.ensure();
+        return (this.chosen = this.server);
+      } catch (e) {
+        if (!(e instanceof ServerUnavailable)) throw e;
+        if (!e.remembered) process.stderr.write(`adbax: on-device server unavailable (${e.message}); using uiautomator dump\n`);
+      }
+    }
+    return (this.chosen = this.shell);
+  }
+
+  async fast() {
+    return (await this.backend()) === this.server;
+  }
+
+  /**
+   * The tree as XML. `afterAction` gives the screen time to react first: on
+   * the server a short settle and then a wait for accessibility events to
+   * stop, on the shell a fixed sleep (uiautomator waits a second on its own).
+   */
+  async dump({ afterAction = false, windows = false } = {}) {
+    const b = await this.backend();
+    if (b === this.server) {
+      const settle = this.settle !== undefined ? +this.settle : afterAction ? 150 : 0;
+      let d = await b.dump({ settle, idle: 300, timeout: afterAction ? 3000 : 2000, windows });
+      // A new activity's window can go quiet before its content is attached,
+      // which reads as an empty screen. Read again until something shows or
+      // two reads agree: a game's canvas stays empty, and that is the answer.
+      for (let i = 0; afterAction && i < 4 && interesting(parseTree(d.xml)).length === 0; i++) {
+        await delay(250);
+        const again = await b.dump({ idle: 300, timeout: 1500, windows });
+        if (again.xml === d.xml) break;
+        d = again;
+      }
+      return d;
+    }
+    if (windows) process.stderr.write('adbax: --windows needs the on-device server; showing the active window only\n');
+    const settle = this.settle !== undefined ? +this.settle : afterAction ? 700 : 0;
+    return b.dump({ settle });
+  }
+
+  async tree(opts) {
+    const { xml } = await this.dump(opts);
+    return parseTree(xml);
+  }
+
+  // Polling loops (wait, scroll-to) can go much faster when a read is cheap.
+  async pollInterval() {
+    return (await this.fast()) ? 150 : 600;
+  }
+
+  async tap(x, y) { return (await this.backend()).tap(x, y); }
+  async swipe(x1, y1, x2, y2, ms) { return (await this.backend()).swipe(x1, y1, x2, y2, ms); }
+
+  async key(codes, opts) { return (await this.backend()).key(codes, opts); }
+
+  async type(text) { return (await this.backend()).type(text); }
+
+  /** The field with input focus: {focused, editable, text, password}, or null if unknown. */
+  async focus() {
+    const b = await this.backend();
+    if (b === this.server) return b.focus();
+    const f = (await this.tree()).find((n) => n.focused && n.editable);
+    return f ? { focused: true, editable: true, text: f.text, password: f.password } : { focused: false };
+  }
+
+  /** Empties the focused field; ACTION_SET_TEXT where possible, a run of DELs where not. */
+  async clear(existingLength = 0) {
+    const b = await this.backend();
+    if (b === this.server && (await b.clear())) return;
+    await this.shell.clear(existingLength);
+  }
+
+  /** Replaces the focused field's text. The field's text afterwards, or null without one. */
+  async setText(text) {
+    const b = await this.backend();
+    if (b === this.server) {
+      try { return (await b.request({ cmd: 'settext', text })).head.text ?? text; } catch (e) { if (process.env.ADBAX_DEBUG) console.error(e); return null; }
+    }
+    await this.shell.clear(4096);
+    await this.shell.type(text);
+    return text;
+  }
+
+  async screenshot(opts) { return (await this.backend()).screenshot(opts); }
+
+  async keyboardUp() {
+    const o = await this.adb.shell('dumpsys input_method | grep -E "mInputShown|mServedView" | head -3', { soft: true });
+    return /mInputShown=true/.test(o);
+  }
+
+  /** Waits for a soft keyboard or an editable field with focus, whichever the device reports. */
+  async waitForInput(ms = 3000) {
+    const deadline = Date.now() + ms;
+    const fast = await this.fast();
+    while (Date.now() < deadline) {
+      if (fast) {
+        const f = await this.server.focus();
+        if (f.focused && f.editable) return true;
+      } else if (await this.keyboardUp()) {
+        await delay(250);
+        return true;
+      }
+      await delay(fast ? 80 : 200);
+    }
+    return false;
+  }
+
+  /**
+   * "package/Activity" on top. From the server when it runs (a few ms), from
+   * dumpsys otherwise (60-200 ms).
+   */
+  async where() {
+    if (this.chosen === this.server) {
+      const a = await this.server.activity().catch(() => null);
+      if (a) return a;
+    }
+    // `dumpsys window displays` is the cheap section; Android 8 and older only
+    // print mCurrentFocus in the full dump.
+    let w = (await this.adb.shell('dumpsys window displays 2>/dev/null | grep -m1 mCurrentFocus', { soft: true })).trim();
+    if (!w) w = (await this.adb.shell('dumpsys window 2>/dev/null | grep -m1 mCurrentFocus', { soft: true })).trim();
+    const m = w.match(/([\w.]+)\/([\w.$]+)/);
+    return m ? `${m[1]}/${m[2]}` : (w || '?');
+  }
+
+  /** The screen as currently rotated: a landscape game is wider than it is tall. */
+  async screenSize(xml) {
+    const info = xml ? screenInfo(xml) : {};
+    if (info.width) return { width: info.width, height: info.height };
+    if ((await this.fast()) && this.server.info && this.server.info.width) {
+      return { width: this.server.info.width, height: this.server.info.height };
+    }
+    const m = (await this.adb.shell('wm size', { soft: true })).match(/(\d+)x(\d+)(?![\s\S]*\d+x\d+)/);
+    if (!m) return { width: 1080, height: 1920 };
+    // `wm size` is the physical, unrotated size.
+    const rot = (await this.adb.shell("dumpsys input | grep -m1 SurfaceOrientation", { soft: true })).match(/(\d)\s*$/);
+    const turned = rot && (rot[1] === '1' || rot[1] === '3');
+    return turned ? { width: +m[2], height: +m[1] } : { width: +m[1], height: +m[2] };
+  }
+
+  // The rows of the last `ui`, so `tap 3` can skip a fresh dump.
+  get rowsFile() {
+    return cachePath(`ui-${serialKey(this.serial)}.json`);
+  }
+
+  saveRows(nodes, all = false) {
+    const rows = interesting(nodes, all);
+    writeJson(this.rowsFile, rows.map(rowRecord));
+    return rows;
+  }
+
+  lastRows() {
+    return readJson(this.rowsFile);
+  }
+
+  // The last screenshot's size, so `--shot` can map its pixels to the screen.
+  get shotFile() {
+    return cachePath(`shot-${serialKey(this.serial)}.json`);
+  }
+
+  saveShot(info) {
+    writeJson(this.shotFile, info);
+  }
+
+  /** Maps a point in the last screenshot's pixels to screen pixels. */
+  fromShot(x, y) {
+    const s = readJson(this.shotFile);
+    if (!s) return null;
+    return [Math.round(x * s.deviceWidth / s.width), Math.round(y * s.deviceHeight / s.height)];
+  }
+}