@houwert/conductor 0.17.0 → 0.18.0

package/dist/commands/capture-ui.js

@@ -14,6 +14,7 @@ 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 a11y_js_1 = require("../drivers/a11y.js");
+const snapshot_store_js_1 = require("../snapshot-store.js");
 async function captureUI(outputPath, opts = {}, sessionName = 'default') {
     try {
         const driver = await (0, runner_js_1.getDriver)(sessionName);
@@ -87,6 +88,9 @@ async function captureUI(outputPath, opts = {}, sessionName = 'default') {
             a11ySnapshot,
             capabilities: { perViewPixels: false, depthData: false },
         };
+        // Persist `@eN` refs so `tap-on @e3` can act on this capture without a
+        // re-query. Keyed by session — see snapshot-store.ts.
+        await (0, snapshot_store_js_1.saveSnapshot)(sessionName, (0, snapshot_store_js_1.buildStoredSnapshot)(a11ySnapshot, { deviceId: sessionName, platform }));
         const json = JSON.stringify(bundle);
         if (outputPath) {
             const resolved = path_1.default.resolve(outputPath);

package/dist/commands/set-viewport.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HELP = void 0;
+exports.setViewport = setViewport;
+exports.HELP = `  set-viewport [<width> <height>]      Resize the web browser viewport (web only)
+    --preset <mobile|tablet|desktop>  Use a device preset instead of explicit width/height
+    --width <n> / --height <n>         Viewport size in CSS pixels
+    --scale <n>                       Device scale factor (default: 2 for mobile/tablet, else 1)
+    --mobile / --no-mobile            Emulate a mobile device (touch + mobile UA hints)
+    --user-agent <str>                Override the user agent string
+    --color-scheme <dark|light>       Emulate prefers-color-scheme`;
+const runner_js_1 = require("../runner.js");
+const web_js_1 = require("../drivers/web.js");
+const output_js_1 = require("../output.js");
+const PRESETS = {
+    mobile: { width: 390, height: 844, deviceScaleFactor: 3, isMobile: true },
+    tablet: { width: 820, height: 1180, deviceScaleFactor: 2, isMobile: true },
+    desktop: { width: 1280, height: 800, deviceScaleFactor: 1, isMobile: false },
+};
+async function setViewport(flags, opts = {}, sessionName = 'default') {
+    let width = flags.width;
+    let height = flags.height;
+    let isMobile = flags.mobile;
+    let scale = flags.scale;
+    if (flags.preset !== undefined) {
+        const preset = PRESETS[flags.preset.toLowerCase()];
+        if (!preset) {
+            (0, output_js_1.printError)(`--preset must be one of: ${Object.keys(PRESETS).join(', ')}`, opts);
+            return 1;
+        }
+        width ?? (width = preset.width);
+        height ?? (height = preset.height);
+        scale ?? (scale = preset.deviceScaleFactor);
+        isMobile ?? (isMobile = preset.isMobile);
+    }
+    if (width === undefined || height === undefined) {
+        (0, output_js_1.printError)('set-viewport requires --preset or both width and height', opts);
+        return 1;
+    }
+    if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) {
+        (0, output_js_1.printError)('set-viewport width and height must be positive numbers', opts);
+        return 1;
+    }
+    if (flags.colorScheme !== undefined &&
+        flags.colorScheme !== 'dark' &&
+        flags.colorScheme !== 'light') {
+        (0, output_js_1.printError)('--color-scheme must be "dark" or "light"', opts);
+        return 1;
+    }
+    const result = await (0, runner_js_1.runDirect)(async (driver) => {
+        if (!(driver instanceof web_js_1.WebDriver)) {
+            throw new Error('set-viewport is only supported on web devices');
+        }
+        await driver.setViewport({
+            width: width,
+            height: height,
+            ...(scale !== undefined ? { deviceScaleFactor: scale } : {}),
+            ...(isMobile !== undefined ? { isMobile } : {}),
+            ...(flags.userAgent !== undefined ? { userAgent: flags.userAgent } : {}),
+            ...(flags.colorScheme !== undefined
+                ? { colorScheme: flags.colorScheme }
+                : {}),
+        });
+    }, sessionName);
+    if (result.success) {
+        (0, output_js_1.printSuccess)(`set-viewport ${width}x${height} — done`, opts);
+        return 0;
+    }
+    else {
+        (0, output_js_1.printError)(`set-viewport ${width}x${height} — failed\n${result.stderr}`, opts);
+        return 1;
+    }
+}

package/dist/commands/tap.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HELP = void 0;
 exports.tap = tap;
-exports.HELP = `  tap-on <element>                     Tap element by text or id
+exports.HELP = `  tap-on <element>                     Tap element by text, id, or @eN snapshot ref
     --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)
@@ -24,6 +24,7 @@ const android_js_1 = require("../drivers/android.js");
 const web_js_1 = require("../drivers/web.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 utils_js_1 = require("../utils.js");
 async function tap(query, opts = {}, sessionName = 'default', flags = {}) {
     if (!query && !flags.id && !flags.text) {
@@ -42,6 +43,9 @@ async function tap(query, opts = {}, sessionName = 'default', flags = {}) {
         ...(flags.leftOf && { leftOf: { query: flags.leftOf } }),
         ...(flags.rightOf && { rightOf: { query: flags.rightOf } }),
     };
+    // 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 result = await (0, runner_js_1.runDirect)(async (driver) => {
         if (driver instanceof ios_js_1.IOSDriver && driver.platform === 'tvos') {
@@ -49,7 +53,16 @@ async function tap(query, opts = {}, sessionName = 'default', flags = {}) {
                 'Use press-key to navigate (e.g. conductor press-key "Remote Dpad Center").');
         }
         let el;
-        if (driver instanceof ios_js_1.IOSDriver) {
+        if (useRef) {
+            const { entry, staleReason } = (0, snapshot_store_js_1.resolveRef)(await (0, snapshot_store_js_1.loadSnapshot)(sessionName), query, {
+                deviceId: sessionName,
+            });
+            if (staleReason) {
+                process.stderr.write(`warning: ${query} — ${staleReason}; re-run capture-ui if the tap misses\n`);
+            }
+            el = { centerX: entry.centerX, centerY: entry.centerY };
+        }
+        else 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) {

package/dist/drivers/a11y.js

@@ -79,6 +79,7 @@ function buildIOSA11y(root) {
             accessibilityOrder = order++;
             snapshot.push({
                 nodeId: path,
+                ref: `@e${accessibilityOrder + 1}`,
                 order: accessibilityOrder,
                 frame: {
                     x: node.frame.X,
@@ -281,6 +282,7 @@ function buildAndroidA11y(xml) {
             accessibilityOrder = order++;
             snapshot.push({
                 nodeId: path,
+                ref: `@e${accessibilityOrder + 1}`,
                 order: accessibilityOrder,
                 frame: {
                     x: n.bounds.x1,
@@ -382,6 +384,7 @@ function buildWebA11y(hierarchy) {
                 accessibilityOrder = order++;
                 snapshot.push({
                     nodeId: path,
+                    ref: `@e${accessibilityOrder + 1}`,
                     order: accessibilityOrder,
                     frame: { x: n.bounds.x, y: n.bounds.y, w: n.bounds.width, h: n.bounds.height },
                     label: n.name,

package/dist/drivers/flow-recorder.js

@@ -38,17 +38,17 @@ async function startRecording(sessionName, out, appId) {
     return target;
 }
 async function finishRecording(sessionName) {
-    const session = (await (0, session_js_1.getSession)(sessionName));
+    const session = await (0, session_js_1.getSession)(sessionName);
     if (!session.recordingPath)
         return null;
     const out = session.recordingPath;
     fs_1.default.appendFileSync(out, `# Recording finished ${new Date().toISOString()}\n`);
-    delete session.recordingPath;
-    await (0, session_js_1.updateSession)(session, sessionName);
+    // Setting to undefined clears the key on save — JSON.stringify drops it.
+    await (0, session_js_1.updateSession)({ recordingPath: undefined }, sessionName);
     return out;
 }
 async function getActiveRecording(sessionName) {
-    const session = (await (0, session_js_1.getSession)(sessionName));
+    const session = await (0, session_js_1.getSession)(sessionName);
     return session.recordingPath ?? null;
 }
 function appendStep(filePath, yamlStep) {

package/dist/drivers/log-sources/metro-discovery.js

@@ -25,13 +25,19 @@ exports.targetsForDevice = targetsForDevice;
 const child_process_1 = require("child_process");
 const metro_js_1 = require("./metro.js");
 const sdk_js_1 = require("../../android/sdk.js");
-/** Metro dev-server port ranges we consider. */
-const METRO_PORT_RANGES = [
-    [8080, 8099], // Metro default range
-    [19000, 19002], // Expo
-];
+/**
+ * Heuristic to reject ports that obviously aren't a Metro dev server (system
+ * ports, well-known services). Candidates that pass are always verified via
+ * {@link fetchTargets} before being returned, so this filter only exists to
+ * keep the number of verification probes bounded.
+ */
 function isMetroPort(port) {
-    return METRO_PORT_RANGES.some(([lo, hi]) => port >= lo && port <= hi);
+    if (port < 1024 || port > 65535)
+        return false;
+    // Skip a handful of common services that share the localhost loopback to
+    // avoid pointless /json probes against them.
+    const wellKnownNonMetro = new Set([3306, 5432, 6379, 27017, 9200, 11211]);
+    return !wellKnownNonMetro.has(port);
 }
 function spawnCapture(cmd, args) {
     return new Promise((resolve, reject) => {

package/dist/drivers/metro-cdp.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MetroCdpClient = void 0;
+exports.selectDebuggerUrl = selectDebuggerUrl;
 exports.resolveDebuggerUrl = resolveDebuggerUrl;
 exports.cdpCall = cdpCall;
 /**
@@ -20,13 +21,15 @@ const ws_1 = __importDefault(require("ws"));
 const metro_js_1 = require("./log-sources/metro.js");
 const metro_discovery_js_1 = require("./log-sources/metro-discovery.js");
 /**
- * Resolve a Metro target's `webSocketDebuggerUrl` honoring deviceId / targetIndex.
- * Throws with a clear message if Metro is unreachable or no target matches.
+ * Pick a debugger `webSocketDebuggerUrl` from an already-fetched target list.
+ * Pure — the async `fetchTargets` / `getDeviceDisplayName` calls happen in
+ * `resolveDebuggerUrl`. `displayName` is the device's resolved display name,
+ * used for device-scoped selection when present. Throws with a clear message
+ * when no target matches.
  */
-async function resolveDebuggerUrl(opts) {
+function selectDebuggerUrl(targets, opts, displayName) {
     const port = opts.port ?? 8081;
     const host = opts.host ?? 'localhost';
-    const targets = await (0, metro_js_1.fetchTargets)(port, host);
     const withWs = targets.filter((t) => t.webSocketDebuggerUrl);
     if (withWs.length === 0) {
         throw new Error(`Metro on ${host}:${port} returned no debugger targets. Is an app running on a device/simulator?`);
@@ -37,18 +40,29 @@ async function resolveDebuggerUrl(opts) {
         }
         return withWs[opts.targetIndex].webSocketDebuggerUrl;
     }
-    if (opts.deviceId && opts.platform) {
-        const displayName = await (0, metro_discovery_js_1.getDeviceDisplayName)(opts.platform, opts.deviceId);
-        if (displayName) {
-            const target = (0, metro_discovery_js_1.selectTargetForDevice)(withWs, displayName);
-            if (target)
-                return target.webSocketDebuggerUrl;
-        }
+    if (displayName) {
+        const target = (0, metro_discovery_js_1.selectTargetForDevice)(withWs, displayName);
+        if (target)
+            return target.webSocketDebuggerUrl;
     }
     // Prefer the Hermes/React target by title, otherwise first.
     const target = withWs.find((t) => t.title && /hermes|react/i.test(t.title)) ?? withWs[0];
     return target.webSocketDebuggerUrl;
 }
+/**
+ * Resolve a Metro target's `webSocketDebuggerUrl` honoring deviceId / targetIndex.
+ * Throws with a clear message if Metro is unreachable or no target matches.
+ */
+async function resolveDebuggerUrl(opts) {
+    const port = opts.port ?? 8081;
+    const host = opts.host ?? 'localhost';
+    const targets = await (0, metro_js_1.fetchTargets)(port, host);
+    let displayName;
+    if (opts.deviceId && opts.platform) {
+        displayName = (await (0, metro_discovery_js_1.getDeviceDisplayName)(opts.platform, opts.deviceId)) ?? undefined;
+    }
+    return selectDebuggerUrl(targets, opts, displayName);
+}
 /**
  * Open a short-lived CDP socket, send a single method, return the result.
  * Closes the socket whether the call succeeds or throws.

package/dist/drivers/web.js

@@ -157,6 +157,9 @@ class WebDriver {
     async eraseAllText(count = 50) {
         await this.post('eraseText', { count });
     }
+    async setViewport(opts) {
+        await this.post('setViewport', opts);
+    }
     // ── Stub methods for mobile-only features ──────────────────────────────────
     // These throw clear errors rather than silently no-op so the user knows
     // the command isn't applicable to web.

package/dist/index.js

@@ -51,6 +51,7 @@ const hide_keyboard_js_1 = require("./commands/hide-keyboard.js");
 const scroll_until_visible_js_1 = require("./commands/scroll-until-visible.js");
 const set_location_js_1 = require("./commands/set-location.js");
 const set_orientation_js_1 = require("./commands/set-orientation.js");
+const set_viewport_js_1 = require("./commands/set-viewport.js");
 const start_device_js_1 = require("./commands/start-device.js");
 const stop_device_js_1 = require("./commands/stop-device.js");
 const delete_device_js_1 = require("./commands/delete-device.js");
@@ -91,6 +92,7 @@ const COMMAND_HELP = {
     'open-link': open_link_js_1.HELP,
     'set-location': set_location_js_1.HELP,
     'set-orientation': set_orientation_js_1.HELP,
+    'set-viewport': set_viewport_js_1.HELP,
     'take-screenshot': screenshot_js_1.HELP,
     'capture-ui': capture_ui_js_1.HELP,
     inspect: inspect_js_1.HELP,
@@ -214,6 +216,11 @@ async function main() {
             'interval',
             'app',
             'since',
+            'preset',
+            'width',
+            'height',
+            'user-agent',
+            'color-scheme',
         ],
         alias: { h: 'help', v: 'verbose', V: 'version' },
     });
@@ -502,6 +509,26 @@ async function main() {
             exitCode = await (0, set_orientation_js_1.setOrientation)(orientation, opts, sessionName);
             break;
         }
+        case 'set-viewport': {
+            exitCode = await (0, set_viewport_js_1.setViewport)({
+                preset: argv['preset'],
+                width: argv['width'] !== undefined
+                    ? Number(argv['width'])
+                    : rest[0] !== undefined
+                        ? Number(rest[0])
+                        : undefined,
+                height: argv['height'] !== undefined
+                    ? Number(argv['height'])
+                    : rest[1] !== undefined
+                        ? Number(rest[1])
+                        : undefined,
+                scale: argv['scale'] !== undefined ? Number(argv['scale']) : undefined,
+                mobile: argv['mobile'],
+                userAgent: argv['user-agent'],
+                colorScheme: argv['color-scheme'],
+            }, opts, sessionName);
+            break;
+        }
         case 'take-screenshot': {
             const outPath = argv['output'];
             const fullPage = Boolean(argv['full-page']);

package/dist/snapshot-store.js

@@ -0,0 +1,96 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SNAPSHOT_STALE_MS = void 0;
+exports.snapshotFilePath = snapshotFilePath;
+exports.isRefQuery = isRefQuery;
+exports.buildStoredSnapshot = buildStoredSnapshot;
+exports.saveSnapshot = saveSnapshot;
+exports.loadSnapshot = loadSnapshot;
+exports.resolveRef = resolveRef;
+/**
+ * Snapshot-scoped ephemeral element refs.
+ *
+ * `capture-ui` assigns each accessible element a short ref (`@e1`, `@e2`, …) and
+ * persists its resolved screen coordinates here, keyed by session. `tap-on @e3`
+ * then taps the cached point directly — no fuzzy text/id matching.
+ *
+ * Refs are deliberately ephemeral: a stale snapshot warns (it does not hard-fail),
+ * and the agent is expected to re-run `capture-ui` and act on fresh refs.
+ */
+const promises_1 = __importDefault(require("fs/promises"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const SNAPSHOTS_DIR = path_1.default.join(os_1.default.homedir(), '.conductor', 'snapshots');
+/** A snapshot older than this is considered stale. */
+exports.SNAPSHOT_STALE_MS = 60000;
+function snapshotFilePath(sessionName = 'default') {
+    return path_1.default.join(SNAPSHOTS_DIR, `${sessionName}.json`);
+}
+/** True when `s` looks like an ephemeral element ref (`@e3`). */
+function isRefQuery(s) {
+    return /^@e\d+$/i.test(s.trim());
+}
+/** Build a `StoredSnapshot` from a freshly built a11y snapshot. */
+function buildStoredSnapshot(entries, device) {
+    const refs = {};
+    for (const e of entries) {
+        refs[e.ref] = {
+            ref: e.ref,
+            centerX: e.frame.x + e.frame.w / 2,
+            centerY: e.frame.y + e.frame.h / 2,
+            frame: e.frame,
+            label: e.label,
+            nodeId: e.nodeId,
+        };
+    }
+    return {
+        version: 1,
+        capturedAt: new Date().toISOString(),
+        deviceId: device.deviceId,
+        platform: device.platform,
+        refs,
+    };
+}
+async function saveSnapshot(sessionName, snapshot) {
+    await promises_1.default.mkdir(SNAPSHOTS_DIR, { recursive: true });
+    await promises_1.default.writeFile(snapshotFilePath(sessionName), JSON.stringify(snapshot, null, 2));
+}
+async function loadSnapshot(sessionName) {
+    try {
+        const data = await promises_1.default.readFile(snapshotFilePath(sessionName), 'utf-8');
+        return JSON.parse(data);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve an `@eN` ref against the session's last `capture-ui` snapshot.
+ * Throws when there is no snapshot or the ref is unknown. `staleReason` is
+ * advisory — callers warn but still act, since refs are explicitly ephemeral.
+ */
+function resolveRef(snapshot, ref, ctx) {
+    if (!snapshot) {
+        throw new Error(`no snapshot for this session — run \`conductor capture-ui\` before using ${ref}`);
+    }
+    const norm = ref.trim().toLowerCase();
+    const key = Object.keys(snapshot.refs).find((k) => k.toLowerCase() === norm);
+    if (!key) {
+        const avail = Object.keys(snapshot.refs);
+        const shown = avail.slice(0, 8).join(', ');
+        throw new Error(`${ref} is not in the last snapshot ` +
+            `(${avail.length} ref${avail.length === 1 ? '' : 's'}: ${shown}${avail.length > 8 ? ', …' : ''})`);
+    }
+    let staleReason = null;
+    const ageMs = Date.now() - new Date(snapshot.capturedAt).getTime();
+    if (ageMs > exports.SNAPSHOT_STALE_MS) {
+        staleReason = `snapshot is ${Math.round(ageMs / 1000)}s old`;
+    }
+    else if (ctx?.deviceId && snapshot.deviceId && ctx.deviceId !== snapshot.deviceId) {
+        staleReason = `snapshot was captured on a different device (${snapshot.deviceId})`;
+    }
+    return { entry: snapshot.refs[key], staleReason };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@houwert/conductor",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "CLI tool for mobile app interactions — optimized for AI agents",
   "license": "MIT",
   "repository": {