@houwert/conductor 0.25.0 → 0.27.0

package/dist/commands/add-media.js

@@ -0,0 +1,36 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HELP = void 0;
+exports.addMedia = addMedia;
+exports.HELP = `  add-media <path>...                  Add image/video files to the device gallery (media-picker testing)`;
+const path_1 = __importDefault(require("path"));
+const fs_1 = __importDefault(require("fs"));
+const runner_js_1 = require("../runner.js");
+const output_js_1 = require("../output.js");
+async function addMedia(files, opts = {}, sessionName = 'default') {
+    if (files.length === 0) {
+        (0, output_js_1.printError)('add-media requires at least one file path', opts);
+        return 1;
+    }
+    const resolved = files.map((f) => path_1.default.resolve(process.cwd(), f));
+    const missing = resolved.filter((f) => !fs_1.default.existsSync(f));
+    if (missing.length > 0) {
+        (0, output_js_1.printError)(`add-media: file(s) not found:\n${missing.join('\n')}`, opts);
+        return 1;
+    }
+    const result = await (0, runner_js_1.runDirect)(async (driver) => {
+        for (const f of resolved)
+            await driver.addMedia(f);
+    }, sessionName);
+    if (result.success) {
+        (0, output_js_1.printSuccess)(`add-media — added ${resolved.length} file(s)`, opts);
+        return 0;
+    }
+    else {
+        (0, output_js_1.printError)(`add-media — failed\n${result.stderr}`, opts);
+        return 1;
+    }
+}

package/dist/commands/airplane-mode.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HELP = void 0;
+exports.setAirplaneMode = setAirplaneMode;
+exports.toggleAirplaneMode = toggleAirplaneMode;
+exports.HELP = `  set-airplane-mode <on|off>           Enable/disable airplane mode (Android only)
+  toggle-airplane-mode                 Flip airplane mode (Android only)`;
+const runner_js_1 = require("../runner.js");
+const android_js_1 = require("../drivers/android.js");
+const output_js_1 = require("../output.js");
+async function setAirplaneMode(value, opts = {}, sessionName = 'default') {
+    const v = value.toLowerCase();
+    if (v !== 'on' && v !== 'off' && v !== 'enable' && v !== 'disable') {
+        (0, output_js_1.printError)('set-airplane-mode requires <on|off>', opts);
+        return 1;
+    }
+    const enabled = v === 'on' || v === 'enable';
+    const result = await (0, runner_js_1.runDirect)(async (driver) => {
+        await driver.setAirplaneMode(enabled);
+    }, sessionName);
+    if (result.success) {
+        (0, output_js_1.printSuccess)(`set-airplane-mode ${enabled ? 'on' : 'off'} — done`, opts);
+        return 0;
+    }
+    else {
+        (0, output_js_1.printError)(`set-airplane-mode ${enabled ? 'on' : 'off'} — failed\n${result.stderr}`, opts);
+        return 1;
+    }
+}
+async function toggleAirplaneMode(opts = {}, sessionName = 'default') {
+    const result = await (0, runner_js_1.runDirect)(async (driver) => {
+        if (!(driver instanceof android_js_1.AndroidDriver)) {
+            throw new Error('toggle-airplane-mode is only supported on Android');
+        }
+        const current = await driver.getAirplaneMode();
+        await driver.setAirplaneMode(!current);
+    }, sessionName);
+    if (result.success) {
+        (0, output_js_1.printSuccess)('toggle-airplane-mode — done', opts);
+        return 0;
+    }
+    else {
+        (0, output_js_1.printError)(`toggle-airplane-mode — failed\n${result.stderr}`, opts);
+        return 1;
+    }
+}

package/dist/commands/assert-screenshot.js

@@ -0,0 +1,68 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HELP = void 0;
+exports.assertScreenshot = assertScreenshot;
+exports.HELP = `  assert-screenshot <reference.png>    Visual regression: compare the screen to a reference image
+    --threshold <0-1>                 Max fraction of differing pixels allowed (default 0.01)
+    --update                          Write/overwrite the reference from the current screen and pass`;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const pngjs_1 = require("pngjs");
+const pixelmatch_1 = __importDefault(require("pixelmatch"));
+const runner_js_1 = require("../runner.js");
+const output_js_1 = require("../output.js");
+async function assertScreenshot(reference, opts = {}, sessionName = 'default', flags = {}) {
+    if (!reference) {
+        (0, output_js_1.printError)('assert-screenshot requires a reference image path', opts);
+        return 1;
+    }
+    const refPath = path_1.default.resolve(process.cwd(), reference);
+    const threshold = flags.threshold ?? 0.01;
+    let shot;
+    const result = await (0, runner_js_1.runDirect)(async (driver) => {
+        shot = await driver.screenshot();
+    }, sessionName);
+    if (!result.success || !shot) {
+        (0, output_js_1.printError)(`assert-screenshot — failed to capture screen\n${result.stderr}`, opts);
+        return 1;
+    }
+    // Seed or refresh the baseline instead of comparing.
+    if (flags.update || !fs_1.default.existsSync(refPath)) {
+        fs_1.default.mkdirSync(path_1.default.dirname(refPath), { recursive: true });
+        fs_1.default.writeFileSync(refPath, shot);
+        const why = flags.update ? 'updated' : 'created (no baseline existed)';
+        (0, output_js_1.printSuccess)(`assert-screenshot — reference ${why}: ${refPath}`, opts);
+        return 0;
+    }
+    const actual = pngjs_1.PNG.sync.read(shot);
+    const expected = pngjs_1.PNG.sync.read(fs_1.default.readFileSync(refPath));
+    if (actual.width !== expected.width || actual.height !== expected.height) {
+        (0, output_js_1.printError)(`assert-screenshot — size mismatch: screen ${actual.width}x${actual.height} vs ` +
+            `reference ${expected.width}x${expected.height}`, opts);
+        return 1;
+    }
+    const { width, height } = expected;
+    const diff = new pngjs_1.PNG({ width, height });
+    const diffPixels = (0, pixelmatch_1.default)(expected.data, actual.data, diff.data, width, height, {
+        threshold: 0.1,
+    });
+    const total = width * height;
+    const ratio = diffPixels / total;
+    if (ratio > threshold) {
+        const diffPath = refPath.replace(/\.png$/i, '') + '.diff.png';
+        fs_1.default.writeFileSync(diffPath, pngjs_1.PNG.sync.write(diff));
+        if (opts.json)
+            (0, output_js_1.printData)({ passed: false, diffPixels, ratio, diffPath }, opts);
+        else
+            (0, output_js_1.printError)(`assert-screenshot — ${(ratio * 100).toFixed(2)}% differs (> ${(threshold * 100).toFixed(2)}% allowed); diff written to ${diffPath}`, opts);
+        return 1;
+    }
+    if (opts.json)
+        (0, output_js_1.printData)({ passed: true, diffPixels, ratio }, opts);
+    else
+        (0, output_js_1.printSuccess)(`assert-screenshot — matches (${(ratio * 100).toFixed(2)}% differ, within ${(threshold * 100).toFixed(2)}%)`, opts);
+    return 0;
+}

package/dist/commands/assert-true.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HELP = void 0;
+exports.assertTrue = assertTrue;
+exports.HELP = `  assert-true <expr>                   Assert a JavaScript expression evaluates truthy (exit 1 if not)
+    --env KEY=VALUE                   Expose an env var to the expression (repeatable)`;
+const js_engine_js_1 = require("../drivers/js-engine.js");
+const output_js_1 = require("../output.js");
+async function assertTrue(expr, opts = {}, env = {}) {
+    if (!expr) {
+        (0, output_js_1.printError)('assert-true requires a JavaScript expression', opts);
+        return 1;
+    }
+    const output = {};
+    try {
+        // Evaluate in the same sandbox the flow runner uses for assertTrue, so
+        // expressions behave identically whether run inline or inside a flow.
+        await (0, js_engine_js_1.executeScript)(`output.__assertTrue = !!(${expr});`, env, output, 'assert-true');
+    }
+    catch (e) {
+        (0, output_js_1.printError)(`assert-true failed to evaluate: ${expr}\n${e.message}`, opts);
+        return 1;
+    }
+    if (output['__assertTrue']) {
+        (0, output_js_1.printSuccess)(`assert-true "${expr}" — passed`, opts);
+        return 0;
+    }
+    (0, output_js_1.printError)(`assert-true "${expr}" — failed`, opts);
+    return 1;
+}

package/dist/commands/copy-text-from.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HELP = void 0;
+exports.copyTextFrom = copyTextFrom;
+exports.HELP = `  copy-text-from <element>             Read an element's text; print it and copy to the device clipboard
+    --id <id>                         Match by accessibility id instead of text
+    --text <text>                     Match by text only (not id)
+    --index <n>                       Pick the nth match (0-based)`;
+const runner_js_1 = require("../runner.js");
+const output_js_1 = require("../output.js");
+const ios_js_1 = require("../drivers/ios.js");
+const android_js_1 = require("../drivers/android.js");
+const web_js_1 = require("../drivers/web.js");
+const vega_js_1 = require("../drivers/vega.js");
+const wait_js_1 = require("../drivers/wait.js");
+const direct_ios_selector_js_1 = require("../drivers/direct-ios-selector.js");
+async function copyTextFrom(query, opts = {}, sessionName = 'default', flags = {}) {
+    if (!query && !flags.id && !flags.text) {
+        (0, output_js_1.printError)('copy-text-from requires <element>, --id <id>, or --text <text>', opts);
+        return 1;
+    }
+    const sel = {
+        ...(flags.text ? { text: flags.text } : flags.id ? { id: flags.id } : { query }),
+        ...(flags.index !== undefined && { index: flags.index }),
+    };
+    const label = flags.text ? `text="${flags.text}"` : flags.id ? `id="${flags.id}"` : `"${query}"`;
+    let copied = '';
+    const result = await (0, runner_js_1.runDirect)(async (driver) => {
+        let el;
+        if (driver instanceof ios_js_1.IOSDriver) {
+            el = await (0, wait_js_1.waitForIOSElement)((o) => driver.viewHierarchy(false, [], { cache: o?.cached }).then((h) => h.axElement), sel, undefined, undefined, (0, direct_ios_selector_js_1.makeIOSDirectResolver)(driver, sel));
+        }
+        else if (driver instanceof web_js_1.WebDriver) {
+            el = await (0, wait_js_1.waitForWebElement)(() => driver.viewHierarchy(), sel);
+        }
+        else if (driver instanceof vega_js_1.VegaDriver) {
+            el = await (0, wait_js_1.waitForAndroidElement)(() => driver.viewHierarchy(), sel);
+        }
+        else if (driver instanceof android_js_1.AndroidDriver) {
+            el = await (0, wait_js_1.waitForAndroidElement)(() => driver.viewHierarchy(), sel);
+        }
+        else {
+            return;
+        }
+        copied = el.text ?? '';
+        // Mirror Maestro's copyTextFrom by also landing the value on the device clipboard
+        // where the platform supports it (iOS simulator). Best-effort — the text is the
+        // primary output regardless.
+        if (driver instanceof ios_js_1.IOSDriver) {
+            await driver.clipboardWrite(copied).catch(() => { });
+        }
+    }, sessionName);
+    if (result.success) {
+        // Print the raw text on stdout so callers can capture it (e.g. `$(conductor copy-text-from ...)`).
+        process.stdout.write(copied + '\n');
+        (0, output_js_1.printSuccess)(`copy-text-from ${label} — copied ${copied.length} chars`, opts);
+        return 0;
+    }
+    else {
+        (0, output_js_1.printError)(`copy-text-from ${label} — failed\n${result.stderr}`, opts);
+        return 1;
+    }
+}

package/dist/commands/record-video.js

@@ -0,0 +1,126 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HELP = void 0;
+exports.recordVideo = recordVideo;
+exports.HELP = `  record-video start [--out <path>]    Start a screen VIDEO recording (distinct from \`flow record\`)
+  record-video stop                    Stop recording and write the video file
+                                       iOS: HEVC .mov via simctl · Android: .mp4 via screenrecord`;
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const child_process_1 = require("child_process");
+const runner_js_1 = require("../runner.js");
+const ios_js_1 = require("../drivers/ios.js");
+const android_js_1 = require("../drivers/android.js");
+const sdk_js_1 = require("../android/sdk.js");
+const output_js_1 = require("../output.js");
+const RECORDINGS_DIR = path_1.default.join(os_1.default.homedir(), '.conductor', 'recordings');
+const ANDROID_REMOTE = '/sdcard/conductor_recording.mp4';
+function stateFile(sessionName) {
+    return path_1.default.join(RECORDINGS_DIR, `${sessionName}.json`);
+}
+async function recordVideo(sub, opts, sessionName, flags = {}) {
+    if (sub === 'start')
+        return start(opts, sessionName, flags);
+    if (sub === 'stop')
+        return stop(opts, sessionName);
+    (0, output_js_1.printError)('record-video expects "start" or "stop"', opts);
+    return 1;
+}
+async function start(opts, sessionName, flags) {
+    const existing = stateFile(sessionName);
+    if (fs_1.default.existsSync(existing)) {
+        (0, output_js_1.printError)(`record-video start — a recording is already active for this session (run \`record-video stop\`)`, opts);
+        return 1;
+    }
+    let state = null;
+    const result = await (0, runner_js_1.runDirect)(async (driver) => {
+        if (driver instanceof ios_js_1.IOSDriver) {
+            const outPath = path_1.default.resolve(process.cwd(), flags.out ?? 'conductor-recording.mov');
+            const proc = (0, child_process_1.spawn)('xcrun', ['simctl', 'io', driver.deviceId ?? 'booted', 'recordVideo', '--codec', 'hevc', outPath], { detached: true, stdio: 'ignore' });
+            proc.unref();
+            state = { pid: proc.pid, platform: 'ios', outPath };
+        }
+        else if (driver instanceof android_js_1.AndroidDriver) {
+            const outPath = path_1.default.resolve(process.cwd(), flags.out ?? 'conductor-recording.mp4');
+            const proc = (0, child_process_1.spawn)((0, sdk_js_1.resolveAndroidTool)('adb'), ['-s', driver.serial, 'shell', 'screenrecord', ANDROID_REMOTE], { detached: true, stdio: 'ignore', env: (0, sdk_js_1.androidSpawnEnv)() });
+            proc.unref();
+            state = { pid: proc.pid, platform: 'android', outPath, serial: driver.serial };
+        }
+        else {
+            throw new Error('record-video is only supported on iOS and Android');
+        }
+    }, sessionName);
+    if (!result.success || !state) {
+        (0, output_js_1.printError)(`record-video start — failed\n${result.stderr}`, opts);
+        return 1;
+    }
+    fs_1.default.mkdirSync(RECORDINGS_DIR, { recursive: true });
+    fs_1.default.writeFileSync(stateFile(sessionName), JSON.stringify(state));
+    const outPath = state.outPath;
+    if (opts.json)
+        (0, output_js_1.printData)({ recording: true, outPath }, opts);
+    else
+        (0, output_js_1.printSuccess)(`record-video start — recording to ${outPath}`, opts);
+    return 0;
+}
+async function stop(opts, sessionName) {
+    const file = stateFile(sessionName);
+    if (!fs_1.default.existsSync(file)) {
+        (0, output_js_1.printError)('record-video stop — no active recording for this session', opts);
+        return 1;
+    }
+    const state = JSON.parse(fs_1.default.readFileSync(file, 'utf-8'));
+    try {
+        if (state.platform === 'ios') {
+            // SIGINT lets simctl flush and finalize the .mov it is writing directly to outPath.
+            try {
+                process.kill(state.pid, 'SIGINT');
+            }
+            catch {
+                /* already gone */
+            }
+            await sleep(800);
+        }
+        else {
+            const adb = (0, sdk_js_1.resolveAndroidTool)('adb');
+            const env = (0, sdk_js_1.androidSpawnEnv)();
+            // screenrecord runs on-device; interrupt it so it finalizes the mp4, then pull it.
+            await run(adb, ['-s', state.serial, 'shell', 'pkill', '-SIGINT', 'screenrecord'], env);
+            await sleep(2000); // allow the file to flush on device
+            try {
+                process.kill(state.pid, 'SIGINT');
+            }
+            catch {
+                /* local adb shell may have exited */
+            }
+            await run(adb, ['-s', state.serial, 'pull', ANDROID_REMOTE, state.outPath], env);
+            await run(adb, ['-s', state.serial, 'shell', 'rm', '-f', ANDROID_REMOTE], env);
+        }
+    }
+    finally {
+        fs_1.default.rmSync(file, { force: true });
+    }
+    if (!fs_1.default.existsSync(state.outPath)) {
+        (0, output_js_1.printError)(`record-video stop — recording stopped but no file at ${state.outPath}`, opts);
+        return 1;
+    }
+    if (opts.json)
+        (0, output_js_1.printData)({ recording: false, outPath: state.outPath }, opts);
+    else
+        (0, output_js_1.printSuccess)(`record-video stop — saved ${state.outPath}`, opts);
+    return 0;
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+function run(cmd, args, env) {
+    return new Promise((resolve) => {
+        const p = (0, child_process_1.spawn)(cmd, args, { stdio: 'ignore', env });
+        p.on('close', () => resolve());
+        p.on('error', () => resolve());
+    });
+}

package/dist/commands/set-permissions.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HELP = void 0;
+exports.setPermissions = setPermissions;
+exports.HELP = `  set-permissions <perm=value>...      Grant/deny app permissions (e.g. camera=allow photos=deny)
+    [<appId>]                         Target app (defaults to the active session's app)
+    perm=value                        Repeatable. value is allow|deny|unset; perm may be "all"
+                                      (e.g. all=allow camera=deny)`;
+const runner_js_1 = require("../runner.js");
+const session_js_1 = require("../session.js");
+const output_js_1 = require("../output.js");
+async function setPermissions(args, opts = {}, sessionName = 'default') {
+    // Split positional args into an optional appId (no '=') and perm=value pairs.
+    const pairs = [];
+    let appIdArg;
+    for (const a of args) {
+        if (a.includes('='))
+            pairs.push(a);
+        else if (appIdArg === undefined)
+            appIdArg = a;
+    }
+    if (pairs.length === 0) {
+        (0, output_js_1.printError)('set-permissions requires at least one perm=value (e.g. camera=allow)', opts);
+        return 1;
+    }
+    const permissions = {};
+    for (const p of pairs) {
+        const idx = p.indexOf('=');
+        const key = p.slice(0, idx).trim();
+        const value = p.slice(idx + 1).trim();
+        if (key)
+            permissions[key] = value;
+    }
+    const session = await (0, session_js_1.getSession)(sessionName);
+    const appId = appIdArg ?? session.appId;
+    if (!appId) {
+        (0, output_js_1.printError)('set-permissions: no appId provided and no active session. Run launch-app first.', opts);
+        return 1;
+    }
+    const summary = Object.entries(permissions)
+        .map(([k, v]) => `${k}=${v}`)
+        .join(' ');
+    const result = await (0, runner_js_1.runDirect)(async (driver) => {
+        await driver.setPermissions(appId, permissions);
+    }, sessionName);
+    if (result.success) {
+        (0, output_js_1.printSuccess)(`set-permissions "${appId}" ${summary} — done`, opts);
+        return 0;
+    }
+    else {
+        (0, output_js_1.printError)(`set-permissions "${appId}" ${summary} — failed\n${result.stderr}`, opts);
+        return 1;
+    }
+}

package/dist/commands/stream-server.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HELP = void 0;
+exports.streamServer = streamServer;
+exports.HELP = `  stream-server                       Start (if needed) and print the live video-stream WebSocket for the device`;
+const runner_js_1 = require("../runner.js");
+const output_js_1 = require("../output.js");
+/**
+ * Ensure the device daemon + streaming-video socket are up and print the
+ * loopback WebSocket URL a viewer subscribes to for the live H.264 stream.
+ * See docs/device-video-stream.md.
+ */
+async function streamServer(opts = {}, sessionName = 'default') {
+    try {
+        const info = await (0, runner_js_1.streamServerInfo)(sessionName);
+        if (opts.json) {
+            (0, output_js_1.printData)(info, opts);
+        }
+        else {
+            console.log(`stream server [${info.device}] (${info.platform}, ${info.codec}): ${info.url}`);
+        }
+        return 0;
+    }
+    catch (err) {
+        (0, output_js_1.printError)(`stream-server — ${err instanceof Error ? err.message : String(err)}`, opts);
+        return 1;
+    }
+}

package/dist/commands/tap.js

@@ -2,12 +2,17 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HELP = void 0;
 exports.tap = tap;
-exports.HELP = `  tap-on <element>                     Tap element by text, id, or @eN snapshot ref
+exports.HELP = `  tap-on [<element>]                   Tap element by text, id, @eN snapshot ref, or coordinate
+    --at <x,y>                        Tap a raw coordinate instead of an element.
+                                      Accepts px ("100,200"), percentages ("50%,50%"),
+                                      or 0-1 fractions ("0.5,0.5"). Skips element matching.
     --id <id>                         Match by accessibility id instead of text
     --text <text>                     Match by text only (not id)
     --index <n>                       Pick the nth match (0-based)
     --long-press                      Hold instead of tap
     --double-tap                      Double-tap the element
+    --repeat <n>                      Tap n times (default 1)
+    --delay <ms>                      Delay between repeated taps (default 100)
     --optional                        Do not fail if element is not found
     --focused                         Match only focused elements
     --enabled / --no-enabled          Match by enabled state
@@ -26,12 +31,15 @@ const vega_js_1 = require("../drivers/vega.js");
 const wait_js_1 = require("../drivers/wait.js");
 const direct_ios_selector_js_1 = require("../drivers/direct-ios-selector.js");
 const snapshot_store_js_1 = require("../snapshot-store.js");
+const flow_runner_js_1 = require("../drivers/flow-runner.js");
 const utils_js_1 = require("../utils.js");
 async function tap(query, opts = {}, sessionName = 'default', flags = {}) {
-    if (!query && !flags.id && !flags.text) {
-        (0, output_js_1.printError)('tap-on requires <element> or --id <id>', opts);
+    if (!query && !flags.id && !flags.text && !flags.at) {
+        (0, output_js_1.printError)('tap-on requires <element>, --id <id>, or --at <x,y>', opts);
         return 1;
     }
+    const repeat = flags.repeat && flags.repeat > 0 ? flags.repeat : 1;
+    const delay = flags.delay ?? 100;
     const sel = {
         ...(flags.text ? { text: flags.text } : flags.id ? { id: flags.id } : { query }),
         ...(flags.index !== undefined && { index: flags.index }),
@@ -47,14 +55,25 @@ async function tap(query, opts = {}, sessionName = 'default', flags = {}) {
     // A bare `@eN` query taps the cached coordinates from the last `capture-ui`
     // snapshot, skipping fuzzy text/id resolution. Explicit --text/--id win.
     const useRef = (0, snapshot_store_js_1.isRefQuery)(query) && !flags.text && !flags.id;
-    const label = flags.text ? `text="${flags.text}"` : flags.id ? `id="${flags.id}"` : `"${query}"`;
+    const label = flags.at
+        ? `@${flags.at}`
+        : flags.text
+            ? `text="${flags.text}"`
+            : flags.id
+                ? `id="${flags.id}"`
+                : `"${query}"`;
     const result = await (0, runner_js_1.runDirect)(async (driver) => {
         if (driver instanceof ios_js_1.IOSDriver && driver.platform === 'tvos') {
             throw new Error('tap-on is not supported on tvOS — Apple TV uses focus-based navigation.\n' +
                 'Use press-key to navigate (e.g. conductor press-key "Remote Dpad Center").');
         }
         let el;
-        if (useRef) {
+        if (flags.at) {
+            // Coordinate tap: skip element resolution entirely.
+            const { x, y } = await (0, flow_runner_js_1.resolvePoint)(flags.at, driver);
+            el = { centerX: x, centerY: y };
+        }
+        else if (useRef) {
             const { entry, staleReason } = (0, snapshot_store_js_1.resolveRef)(await (0, snapshot_store_js_1.loadSnapshot)(sessionName), query, {
                 deviceId: sessionName,
             });
@@ -79,23 +98,27 @@ async function tap(query, opts = {}, sessionName = 'default', flags = {}) {
         else {
             return;
         }
-        if (flags.longPress) {
-            if (driver instanceof android_js_1.AndroidDriver) {
-                await driver.swipe(el.centerX, el.centerY, el.centerX, el.centerY, 1500);
+        for (let i = 0; i < repeat; i++) {
+            if (i > 0)
+                await (0, utils_js_1.sleep)(delay);
+            if (flags.longPress) {
+                if (driver instanceof android_js_1.AndroidDriver) {
+                    await driver.swipe(el.centerX, el.centerY, el.centerX, el.centerY, 1500);
+                }
+                else {
+                    // iOS, web, and vega express a long press as a held tap.
+                    await driver.tap(el.centerX, el.centerY, 1.5);
+                }
+            }
+            else if (flags.doubleTap) {
+                await driver.tap(el.centerX, el.centerY);
+                await (0, utils_js_1.sleep)(100);
+                await driver.tap(el.centerX, el.centerY);
             }
             else {
-                // iOS, web, and vega express a long press as a held tap.
-                await driver.tap(el.centerX, el.centerY, 1.5);
+                await driver.tap(el.centerX, el.centerY);
             }
         }
-        else if (flags.doubleTap) {
-            await driver.tap(el.centerX, el.centerY);
-            await (0, utils_js_1.sleep)(100);
-            await driver.tap(el.centerX, el.centerY);
-        }
-        else {
-            await driver.tap(el.centerX, el.centerY);
-        }
     }, sessionName);
     const verb = flags.longPress ? 'long-press' : flags.doubleTap ? 'double-tap' : 'tap';
     if (result.success) {

package/dist/commands/travel.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HELP = void 0;
+exports.travel = travel;
+exports.HELP = `  travel <lat,lng>...                  Move the device GPS through a series of coordinates
+    --speed <m/s>                     Walk between points at this speed (adds realistic delays)`;
+const runner_js_1 = require("../runner.js");
+const output_js_1 = require("../output.js");
+const utils_js_1 = require("../utils.js");
+const EARTH_RADIUS = 6371000; // meters
+function haversine(a, b) {
+    const dLat = ((b.lat - a.lat) * Math.PI) / 180;
+    const dLon = ((b.lng - a.lng) * Math.PI) / 180;
+    const h = Math.sin(dLat / 2) ** 2 +
+        Math.cos((a.lat * Math.PI) / 180) * Math.cos((b.lat * Math.PI) / 180) * Math.sin(dLon / 2) ** 2;
+    return 2 * EARTH_RADIUS * Math.asin(Math.sqrt(h));
+}
+async function travel(coords, opts = {}, sessionName = 'default', flags = {}) {
+    const points = coords.map((c) => {
+        const [lat, lng] = c.split(',').map((s) => Number(s.trim()));
+        return { lat, lng };
+    });
+    if (points.length === 0 || points.some((p) => Number.isNaN(p.lat) || Number.isNaN(p.lng))) {
+        (0, output_js_1.printError)('travel requires one or more "lat,lng" coordinates', opts);
+        return 1;
+    }
+    const speed = flags.speed;
+    const result = await (0, runner_js_1.runDirect)(async (driver) => {
+        for (let i = 0; i < points.length; i++) {
+            await driver.setLocation(points[i].lat, points[i].lng);
+            if (i < points.length - 1 && speed && speed > 0) {
+                const distM = haversine(points[i], points[i + 1]);
+                await (0, utils_js_1.sleep)(Math.min(Math.round((distM / speed) * 1000), 10000)); // cap 10s/step
+            }
+        }
+    }, sessionName);
+    if (result.success) {
+        (0, output_js_1.printSuccess)(`travel — visited ${points.length} point(s)`, opts);
+        return 0;
+    }
+    else {
+        (0, output_js_1.printError)(`travel — failed\n${result.stderr}`, opts);
+        return 1;
+    }
+}