@houwert/conductor 0.26.0 → 0.27.1

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/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;
+    }
+}

package/dist/drivers/android.js

@@ -75,6 +75,10 @@ class AndroidDriver {
         this._recordingProcess = null;
         this._recordingOutputPath = '';
     }
+    /** adb serial of the target device (used by out-of-process helpers like record-video). */
+    get serial() {
+        return this.deviceId;
+    }
     async connect() {
         const packageDef = loadPackageDef();
         // eslint-disable-next-line @typescript-eslint/no-explicit-any

package/dist/drivers/flow-runner.js

@@ -6,11 +6,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseFlowFile = parseFlowFile;
 exports.parseFlowString = parseFlowString;
 exports.executeFlow = executeFlow;
+exports.resolvePoint = resolvePoint;
+exports.resolvePath = resolvePath;
 /**
  * Native Conductor YAML flow parser and executor.
  * Parses flow YAML files and executes commands directly using IOSDriver / AndroidDriver.
  */
 const promises_1 = __importDefault(require("fs/promises"));
+const node_fs_1 = require("node:fs");
 const path_1 = __importDefault(require("path"));
 const node_vm_1 = __importDefault(require("node:vm"));
 const js_yaml_1 = __importDefault(require("js-yaml"));
@@ -1367,8 +1370,72 @@ async function executeCommandBody(key, val, driver, opts) {
     }
 }
 // ── Utilities ─────────────────────────────────────────────────────────────────
+// Resolve a `file:` reference from within a flow. A path starting with `@` is an
+// alias of the form `@name/rest`, where `name` maps to a directory declared under
+// `paths:` in the nearest `config.yaml`. Everything else keeps the historical
+// behavior: resolved relative to the flow file's directory (`cwd`).
+// Mirrors the plexinc/maestro FlowPathResolver.
 function resolvePath(filePath, cwd) {
-    return path_1.default.isAbsolute(filePath) ? filePath : path_1.default.join(cwd ?? process.cwd(), filePath);
+    const base = cwd ?? process.cwd();
+    if (filePath.startsWith('@'))
+        return resolvePathAlias(filePath, base);
+    return path_1.default.isAbsolute(filePath) ? filePath : path_1.default.join(base, filePath);
+}
+const CONFIG_FILE_NAMES = ['config.yaml', 'config.yml'];
+// Cache discovered config → paths map for the process lifetime (flows are short-lived).
+const configPathsCache = new Map();
+function resolvePathAlias(requestedPath, startDir) {
+    const body = requestedPath.slice(1);
+    const separator = body.indexOf('/');
+    const alias = separator >= 0 ? body.slice(0, separator) : body;
+    const remainder = separator >= 0 ? body.slice(separator + 1) : '';
+    const configPath = findWorkspaceConfig(startDir);
+    if (!configPath) {
+        throw new Error(`Path alias '@${alias}' used but no config.yaml was found in any parent directory. ` +
+            'Declare aliases under `paths:` in a workspace config.yaml.');
+    }
+    const paths = readWorkspacePaths(configPath);
+    const target = paths[alias];
+    if (target === undefined) {
+        const known = Object.keys(paths).sort();
+        throw new Error(`Unknown path alias '@${alias}' referenced in a flow. ` +
+            `Known aliases in ${configPath}: [${known.join(', ')}]`);
+    }
+    const configDir = path_1.default.dirname(path_1.default.resolve(configPath));
+    const targetDir = path_1.default.normalize(path_1.default.resolve(configDir, target));
+    if (!(0, node_fs_1.existsSync)(targetDir) || !(0, node_fs_1.statSync)(targetDir).isDirectory()) {
+        throw new Error(`Path alias '@${alias}' points to '${targetDir}', which is not an existing directory.`);
+    }
+    return path_1.default.normalize(path_1.default.resolve(targetDir, remainder));
+}
+function findWorkspaceConfig(startDir) {
+    let dir = path_1.default.resolve(startDir);
+    while (dir) {
+        for (const name of CONFIG_FILE_NAMES) {
+            const candidate = path_1.default.join(dir, name);
+            if ((0, node_fs_1.existsSync)(candidate))
+                return candidate;
+        }
+        const parent = path_1.default.dirname(dir);
+        dir = parent === dir ? null : parent;
+    }
+    return null;
+}
+function readWorkspacePaths(configPath) {
+    const cached = configPathsCache.get(configPath);
+    if (cached)
+        return cached;
+    let paths = {};
+    try {
+        const doc = js_yaml_1.default.load((0, node_fs_1.readFileSync)(configPath, 'utf-8'));
+        if (doc && typeof doc.paths === 'object' && doc.paths)
+            paths = doc.paths;
+    }
+    catch {
+        // A malformed config leaves aliases unresolved; the unknown-alias error below is clearer.
+    }
+    configPathsCache.set(configPath, paths);
+    return paths;
 }
 function resolveAppId(val, cmdName) {
     if (typeof val === 'string' && val)

package/dist/index.js

@@ -66,6 +66,14 @@ const metro_js_1 = require("./commands/metro.js");
 const clipboard_js_1 = require("./commands/clipboard.js");
 const options_js_1 = require("./commands/options.js");
 const web_targets_js_1 = require("./commands/web-targets.js");
+const copy_text_from_js_1 = require("./commands/copy-text-from.js");
+const assert_true_js_1 = require("./commands/assert-true.js");
+const set_permissions_js_1 = require("./commands/set-permissions.js");
+const add_media_js_1 = require("./commands/add-media.js");
+const airplane_mode_js_1 = require("./commands/airplane-mode.js");
+const travel_js_1 = require("./commands/travel.js");
+const record_video_js_1 = require("./commands/record-video.js");
+const assert_screenshot_js_1 = require("./commands/assert-screenshot.js");
 const session_js_2 = require("./session.js");
 const device_picker_js_1 = require("./device-picker.js");
 const cdp_discovery_js_1 = require("./drivers/cdp-discovery.js");
@@ -109,6 +117,7 @@ const COMMAND_HELP = {
     'clear-state': clear_state_js_1.HELP,
     'uninstall-app': uninstall_app_js_1.HELP,
     'tap-on': tap_js_1.HELP,
+    'copy-text-from': copy_text_from_js_1.HELP,
     'input-text': type_js_1.HELP,
     'erase-text': erase_text_js_1.HELP,
     back: back_js_1.HELP,
@@ -119,8 +128,15 @@ const COMMAND_HELP = {
     'scroll-until-visible': scroll_until_visible_js_1.HELP,
     'assert-visible': assert_visible_js_1.HELP,
     'assert-not-visible': assert_not_visible_js_1.HELP,
+    'assert-true': assert_true_js_1.HELP,
+    'assert-screenshot': assert_screenshot_js_1.HELP,
     'open-link': open_link_js_1.HELP,
     'set-location': set_location_js_1.HELP,
+    'set-permissions': set_permissions_js_1.HELP,
+    'add-media': add_media_js_1.HELP,
+    'set-airplane-mode': airplane_mode_js_1.HELP,
+    travel: travel_js_1.HELP,
+    'record-video': record_video_js_1.HELP,
     'set-orientation': set_orientation_js_1.HELP,
     'set-viewport': set_viewport_js_1.HELP,
     'take-screenshot': screenshot_js_1.HELP,
@@ -206,6 +222,7 @@ async function main() {
             'global',
             'force',
             'yes',
+            'update',
         ],
         string: [
             'device',
@@ -270,6 +287,11 @@ async function main() {
             'react-tag',
             'path',
             'value',
+            'repeat',
+            'delay',
+            'speed',
+            'threshold',
+            'reference',
         ],
         alias: { h: 'help', v: 'verbose', V: 'version', o: 'output', y: 'yes' },
     });
@@ -315,6 +337,8 @@ async function main() {
         'workspace',
         'list-options',
         'web-targets',
+        // assert-true evaluates a pure JS expression in the flow sandbox — no device involved.
+        'assert-true',
         // `logs --list` and `logs --source metro` only query Metro on localhost — no device needed
         // `logs` always needs a device session — Metro discovery is device-scoped.
         // `daemon-stop --all` stops every daemon — no device needed
@@ -587,6 +611,9 @@ async function main() {
             exitCode = await (0, tap_js_1.tap)(element, opts, sessionName, {
                 id: argv['id'],
                 text: argv['text'],
+                at: argv['at'],
+                repeat: argv['repeat'] !== undefined ? Number(argv['repeat']) : undefined,
+                delay: argv['delay'] !== undefined ? Number(argv['delay']) : undefined,
                 index: argv['index'] !== undefined ? Number(argv['index']) : undefined,
                 longPress: argv['long-press'],
                 doubleTap: argv['double-tap'],
@@ -702,6 +729,35 @@ async function main() {
             });
             break;
         }
+        case 'assert-true': {
+            const expr = rest.join(' ');
+            const env = {};
+            const envArgs = [].concat(argv['env'] ?? []);
+            for (const e of envArgs) {
+                const idx = e.indexOf('=');
+                if (idx > 0)
+                    env[e.slice(0, idx)] = e.slice(idx + 1);
+            }
+            exitCode = await (0, assert_true_js_1.assertTrue)(expr, opts, env);
+            break;
+        }
+        case 'assert-screenshot': {
+            const reference = rest[0] ?? argv['reference'] ?? '';
+            exitCode = await (0, assert_screenshot_js_1.assertScreenshot)(reference, opts, sessionName, {
+                threshold: argv['threshold'] !== undefined ? Number(argv['threshold']) : undefined,
+                update: argv['update'],
+            });
+            break;
+        }
+        case 'copy-text-from': {
+            const element = rest.join(' ');
+            exitCode = await (0, copy_text_from_js_1.copyTextFrom)(element, opts, sessionName, {
+                id: argv['id'],
+                text: argv['text'],
+                index: argv['index'] !== undefined ? Number(argv['index']) : undefined,
+            });
+            break;
+        }
         case 'open-link': {
             const url = rest[0] ?? argv['url'] ?? '';
             exitCode = await (0, open_link_js_1.openLink)(url, opts, sessionName);
@@ -719,6 +775,35 @@ async function main() {
             }
             break;
         }
+        case 'set-permissions': {
+            exitCode = await (0, set_permissions_js_1.setPermissions)(rest.map(String), opts, sessionName);
+            break;
+        }
+        case 'add-media': {
+            exitCode = await (0, add_media_js_1.addMedia)(rest.map(String), opts, sessionName);
+            break;
+        }
+        case 'set-airplane-mode': {
+            const value = rest[0] ?? '';
+            exitCode = await (0, airplane_mode_js_1.setAirplaneMode)(value, opts, sessionName);
+            break;
+        }
+        case 'toggle-airplane-mode': {
+            exitCode = await (0, airplane_mode_js_1.toggleAirplaneMode)(opts, sessionName);
+            break;
+        }
+        case 'travel': {
+            exitCode = await (0, travel_js_1.travel)(rest.map(String), opts, sessionName, {
+                speed: argv['speed'] !== undefined ? Number(argv['speed']) : undefined,
+            });
+            break;
+        }
+        case 'record-video': {
+            exitCode = await (0, record_video_js_1.recordVideo)(rest[0] ?? '', opts, sessionName, {
+                out: argv['out'],
+            });
+            break;
+        }
         case 'set-orientation': {
             const orientation = (rest[0] ??
                 argv['orientation'] ??

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@houwert/conductor",
-  "version": "0.26.0",
+  "version": "0.27.1",
   "description": "CLI tool for mobile app interactions — optimized for AI agents",
   "license": "MIT",
   "repository": {
@@ -33,13 +33,16 @@
     "@grpc/proto-loader": "^0.7.15",
     "js-yaml": "^4.1.1",
     "minimist": "^1.2.8",
+    "pixelmatch": "^7.2.0",
     "playwright-core": "^1.52.0",
+    "pngjs": "^7.0.0",
     "ws": "^8.20.0"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",
     "@types/minimist": "^1.2.5",
     "@types/node": "^20.0.0",
+    "@types/pngjs": "^6.0.5",
     "@types/ws": "^8.18.1",
     "@typescript-eslint/eslint-plugin": "^8.56.1",
     "@typescript-eslint/parser": "^8.56.1",

package/skills/conductor-device-interact/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: conductor-device-interact
-description: Drive a running iOS simulator, Android emulator, tvOS simulator, Vega (Amazon Fire TV) virtual device, or Playwright web app with the conductor CLI. Use when launching apps, tapping UI elements, typing text, scrolling/swiping, performing gestures, pressing hardware/keyboard/remote keys, opening URLs or deep links, navigating back, or verifying an app change in the real running app.
+description: Drive a running iOS simulator, Android emulator, tvOS simulator, Vega (Amazon Fire TV) virtual device, or Playwright web app with the conductor CLI. Use when launching apps, tapping UI elements (by selector or raw coordinate), typing text, scrolling/swiping, performing gestures, pressing hardware/keyboard/remote keys, opening URLs or deep links, navigating back, granting/denying app permissions, adding media to the gallery, setting GPS location or a travel route, toggling airplane mode, recording a screen video, or verifying an app change in the real running app.
 ---
 
 # Conductor — device interaction
@@ -36,7 +36,9 @@ conductor assert-visible "Dashboard"
 |---|---|
 | `conductor launch-app <appId>` | Launch app (saved to session). `--no-stop-app` resumes; `--argument key=value` passes launch args |
 | `conductor stop-app [<appId>]` | Stop the app |
-| `conductor tap-on <element>` | Tap by text, id, or `@eN`. `--long-press`, `--double-tap`, `--optional`, `--index <n>` |
+| `conductor tap-on <element>` | Tap by text, id, or `@eN`. `--long-press`, `--double-tap`, `--optional`, `--index <n>`, `--repeat <n> --delay <ms>` |
+| `conductor tap-on --at <x,y>` | Tap a raw coordinate (px `100,200`, percent `50%,50%`, or `0-1` fraction) — no element match |
+| `conductor copy-text-from <element>` | Print an element's text (and copy to the iOS clipboard) |
 | `conductor input-text <text>` | Type into the focused field |
 | `conductor erase-text [n]` | Erase n characters (default 50) |
 | `conductor press-key <key>` | Press a key (Enter, Backspace, Home, …) or a remote button (`Remote Dpad Up/Down/Left/Right/Center`, `Remote Menu`) for tvOS / Android TV / vega. `--long-press` / `--duration <seconds>` holds it |
@@ -49,6 +51,11 @@ conductor assert-visible "Dashboard"
 | `conductor pinch [--scale N] [--center x,y]` | Two-finger pinch (scale<1 out, >1 in) |
 | `conductor rotate-gesture [--degrees N] [--center x,y]` | Two-finger rotate |
 | `conductor gesture <json\|--file path>` | Play a multi-touch path |
+| `conductor set-permissions <perm=value>...` | Grant/deny app permissions (`camera=allow photos=deny`, `all=allow`) |
+| `conductor add-media <path>...` | Push image/video files into the device gallery |
+| `conductor set-airplane-mode <on\|off>` / `toggle-airplane-mode` | Airplane mode (Android only) |
+| `conductor travel <lat,lng>... [--speed <m/s>]` | Move GPS through a route of coordinates |
+| `conductor record-video start [--out <path>]` / `record-video stop` | Record a screen **video** (iOS/Android). Distinct from `flow record` (which records a YAML flow) |
 | `conductor clipboard read` / `clipboard write <text>` / `paste` | Clipboard (iOS) |
 | `conductor list-options [command]` | List valid values for enumerated params |
 | `conductor input-server` | Start (if needed) and print the streaming-input WebSocket URL for the device |

package/skills/conductor-inspect/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: conductor-inspect
-description: Read the live UI state of a running app with the conductor CLI — view hierarchy, accessibility snapshot, screenshots, focused element, and element refs. Use when you need to see what's on screen, find an element's id/text/coordinates, take a screenshot, check focus, or assert that something is (or isn't) visible before or after acting.
+description: Read the live UI state of a running app with the conductor CLI — view hierarchy, accessibility snapshot, screenshots, focused element, and element refs. Use when you need to see what's on screen, find an element's id/text/coordinates, take a screenshot, check focus, assert that something is (or isn't) visible, assert a JavaScript expression, or do visual-regression screenshot comparison before or after acting.
 ---
 
 # Conductor — inspection & assertions
@@ -78,6 +78,8 @@ conductor native-image 816,286,288,288 --output /tmp/avatar.png
 |---|---|
 | `conductor assert-visible <element> [--timeout ms]` | Assert element is visible (non-zero exit on failure) |
 | `conductor assert-not-visible <element> [--timeout ms]` | Assert element is absent |
+| `conductor assert-true <expr> [--env K=V]` | Assert a JavaScript expression is truthy (no device needed) |
+| `conductor assert-screenshot <reference.png> [--threshold <0-1>] [--update]` | Visual regression vs a baseline image; `--update` (re)writes the baseline. Writes `<ref>.diff.png` on mismatch |
 
 Both take the same selectors as `tap-on`: `--id`, `--text`, `--index`,
 `--below` / `--above` / `--left-of` / `--right-of`, `--focused`, `--enabled`,