@houwert/conductor 0.17.0 → 0.19.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/clear-state.js

@@ -2,7 +2,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HELP = void 0;
 exports.clearState = clearState;
-exports.HELP = `  clear-state [<appId>]                Clear app data/state`;
+exports.HELP = `  clear-state [<appId>]                DESTRUCTIVE: wipe app data and signed-in state.
+                                       On iOS this uninstall+reinstalls the app, which also drops
+                                       the app's keychain items — the user will be signed out and
+                                       cannot be recovered without their credentials. Do not use to
+                                       reset focus or navigation state.`;
 const runner_js_1 = require("../runner.js");
 const session_js_1 = require("../session.js");
 const output_js_1 = require("../output.js");
@@ -13,6 +17,8 @@ async function clearState(appId, opts = {}, sessionName = 'default') {
         (0, output_js_1.printError)('clear-state: no appId provided and no active session. Run launch-app first.', opts);
         return 1;
     }
+    process.stderr.write('warning: clear-state wipes app data AND signed-in state; the user will be signed out ' +
+        'and cannot be recovered without their credentials.\n');
     const result = await (0, runner_js_1.runDirect)(async (driver) => {
         await driver.clearAppState(resolvedAppId);
     }, sessionName);

package/dist/commands/launch-app.js

@@ -3,8 +3,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.HELP = void 0;
 exports.launchApp = launchApp;
 exports.HELP = `  launch-app <appId>                  Launch app (saves to session)
-    --clear-state                     Clear app data/state before launching
-    --clear-keychain                  Clear keychain before launching
+    --clear-state                     DESTRUCTIVE: wipe app data AND signed-in state before launching.
+                                      On iOS this uninstall+reinstalls the app, which also drops the
+                                      app's keychain items — the user will be signed out and you
+                                      cannot undo it without their credentials. Do not use to reset
+                                      focus or navigation state; relaunch without this flag instead.
+    --clear-keychain                  DESTRUCTIVE: wipe the device keychain before launching. Signs
+                                      the user out of every app on the simulator. Cannot be undone
+                                      without re-entering credentials.
     --no-stop-app                     Do not stop the app before launching (resume instead of restart)
     --argument key=value              Set launch argument (repeatable)`;
 const runner_js_1 = require("../runner.js");
@@ -19,6 +25,10 @@ async function launchApp(appId, deviceId, opts = {}, sessionName = 'default', fl
         return 1;
     }
     await (0, session_js_1.updateSession)({ appId, ...(deviceId ? { deviceId } : {}) }, sessionName);
+    if (flags.clearState || flags.clearKeychain) {
+        process.stderr.write('warning: --clear-state / --clear-keychain wipes app data AND signed-in state; ' +
+            'the user will be signed out and cannot be recovered without their credentials.\n');
+    }
     const result = await (0, runner_js_1.runDirect)(async (driver) => {
         if (flags.clearKeychain)
             await driver.clearKeychain();

package/dist/commands/screenshot.js

@@ -5,24 +5,108 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HELP = void 0;
 exports.screenshot = screenshot;
-exports.HELP = `  take-screenshot [--output <path>] [--full-page]
-                                       Take screenshot (--full-page: web only, capture entire scrollable page)`;
+exports.HELP = `  take-screenshot [<element>] [--output <path>] [--full-page]
+                                       Take screenshot (--full-page: web only, capture entire scrollable page)
+    <element>                         Crop to the element matched by text (positional)
+    --id <id>                         Crop to the element matched by accessibility id
+    --text <text>                     Crop to the element matched by text only (not id)
+    --index <n>                       Pick the nth match (0-based)
+    --margin <px>                     Extra pixels around the crop (default 8) to capture shadows
+    --focused                         Match only focused elements
+    --enabled / --no-enabled          Match by enabled state
+    --checked / --no-checked          Match by checked state
+    --selected / --no-selected        Match by selected state
+    --below <text>                    Match element below the given reference
+    --above <text>                    Match element above the given reference
+    --left-of <text>                  Match element left of the given reference
+    --right-of <text>                 Match element right of the given reference`;
 const path_1 = __importDefault(require("path"));
 const promises_1 = __importDefault(require("fs/promises"));
 const runner_js_1 = require("../runner.js");
 const output_js_1 = require("../output.js");
-async function screenshot(outputPath, opts = {}, sessionName = 'default', fullPage = false) {
+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 wait_js_1 = require("../drivers/wait.js");
+const direct_ios_selector_js_1 = require("../drivers/direct-ios-selector.js");
+const png_crop_js_1 = require("../png-crop.js");
+const DEFAULT_MARGIN_PX = 8;
+async function screenshot(outputPath, opts = {}, sessionName = 'default', fullPage = false, query = '', flags = {}) {
     const timestamp = Date.now();
     const defaultName = `screenshot-${timestamp}.png`;
     const resolvedPath = outputPath
         ? path_1.default.resolve(outputPath)
         : path_1.default.resolve(process.cwd(), defaultName);
+    const hasSelector = !!(query || flags.id || flags.text);
+    const sel = hasSelector
+        ? {
+            ...(flags.text ? { text: flags.text } : flags.id ? { id: flags.id } : { query }),
+            ...(flags.index !== undefined && { index: flags.index }),
+            ...(flags.focused !== undefined && { focused: flags.focused }),
+            ...(flags.enabled !== undefined && { enabled: flags.enabled }),
+            ...(flags.checked !== undefined && { checked: flags.checked }),
+            ...(flags.selected !== undefined && { selected: flags.selected }),
+            ...(flags.below && { below: { query: flags.below } }),
+            ...(flags.above && { above: { query: flags.above } }),
+            ...(flags.leftOf && { leftOf: { query: flags.leftOf } }),
+            ...(flags.rightOf && { rightOf: { query: flags.rightOf } }),
+        }
+        : null;
+    const label = flags.text
+        ? `text="${flags.text}"`
+        : flags.id
+            ? `id="${flags.id}"`
+            : query
+                ? `"${query}"`
+                : '';
+    const margin = flags.margin ?? DEFAULT_MARGIN_PX;
     const result = await (0, runner_js_1.runDirect)(async (driver) => {
         const buf = await driver.screenshot({ fullPage });
-        await promises_1.default.writeFile(resolvedPath, buf);
+        let out = buf;
+        if (sel) {
+            let el;
+            let hierarchyW;
+            let hierarchyH;
+            if (driver instanceof ios_js_1.IOSDriver) {
+                const h = await driver.viewHierarchy(false, [], { cache: false });
+                hierarchyW = h.axElement.frame.Width;
+                hierarchyH = h.axElement.frame.Height;
+                el = await (0, wait_js_1.waitForIOSElement)((o) => driver.viewHierarchy(false, [], { cache: o?.cached }).then((x) => x.axElement), sel, undefined, undefined, (0, direct_ios_selector_js_1.makeIOSDirectResolver)(driver, sel));
+            }
+            else if (driver instanceof web_js_1.WebDriver) {
+                const info = await driver.deviceInfo();
+                hierarchyW = info.widthPixels;
+                hierarchyH = info.heightPixels;
+                el = await (0, wait_js_1.waitForWebElement)(() => driver.viewHierarchy(), sel);
+            }
+            else if (driver instanceof android_js_1.AndroidDriver) {
+                const xml = await driver.viewHierarchy();
+                // Android XML root bounds: derive from the first parseable <node bounds="[0,0][W,H]">
+                const m = xml.match(/<node[^>]*bounds="\[0,0\]\[(\d+),(\d+)\]"/);
+                hierarchyW = m ? +m[1] : 0;
+                hierarchyH = m ? +m[2] : 0;
+                el = await (0, wait_js_1.waitForAndroidElement)(() => driver.viewHierarchy(), sel);
+            }
+            else {
+                throw new Error('selector cropping is not supported for this driver');
+            }
+            const { width: pngW, height: pngH } = (0, png_crop_js_1.readPngDimensions)(buf);
+            const scaleX = hierarchyW > 0 ? pngW / hierarchyW : 1;
+            const scaleY = hierarchyH > 0 ? pngH / hierarchyH : 1;
+            const rectX = Math.round(el.bounds.x * scaleX - margin);
+            const rectY = Math.round(el.bounds.y * scaleY - margin);
+            const rectW = Math.round(el.bounds.width * scaleX + margin * 2);
+            const rectH = Math.round(el.bounds.height * scaleY + margin * 2);
+            if (rectX + rectW <= 0 || rectY + rectH <= 0 || rectX >= pngW || rectY >= pngH) {
+                throw new Error(`element ${label} bounds [${rectX},${rectY} ${rectW}x${rectH}] are outside the screenshot (${pngW}x${pngH})`);
+            }
+            out = (0, png_crop_js_1.cropPng)(buf, { x: rectX, y: rectY, width: rectW, height: rectH });
+        }
+        await promises_1.default.writeFile(resolvedPath, out);
     }, sessionName);
     if (result.success) {
-        (0, output_js_1.printSuccess)(`screenshot saved to ${resolvedPath}`, opts);
+        const suffix = sel ? ` (${label})` : '';
+        (0, output_js_1.printSuccess)(`screenshot saved to ${resolvedPath}${suffix}`, opts);
         return 0;
     }
     else {

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/daemon/server.js

@@ -110,7 +110,7 @@ async function ensureDriverRunning() {
             }
             else if (driverPlatform === 'tvos') {
                 // Health-check restart — don't dismiss, to avoid disrupting user's app
-                await (0, bootstrap_js_1.startTvOSDriver)(sessionName, driverPort, /* dismissAfterLaunch */ false);
+                await (0, bootstrap_js_1.startTvOSDriver)(sessionName, driverPort, /* restoreFocusAfterLaunch */ false);
             }
             else if (driverPlatform === 'web') {
                 await (0, web_server_js_1.startWebServer)(driverPort, (0, bootstrap_js_1.webBrowserName)(sessionName), dlog, cdpUrl, cdpTargetId);
@@ -357,8 +357,9 @@ async function main() {
                             await (0, bootstrap_js_1.startIOSDriver)(sessionName, driverPort);
                         }
                         else if (platform === 'tvos') {
-                            // First install — dismiss the runner app to return to homescreen
-                            await (0, bootstrap_js_1.startTvOSDriver)(sessionName, driverPort, /* dismissAfterLaunch */ true);
+                            // First install — the runner takes foreground; ask it to hand
+                            // focus back to whatever app the user had open.
+                            await (0, bootstrap_js_1.startTvOSDriver)(sessionName, driverPort, /* restoreFocusAfterLaunch */ true);
                         }
                         else if (platform === 'web') {
                             await (0, web_server_js_1.startWebServer)(driverPort, (0, bootstrap_js_1.webBrowserName)(sessionName), dlog, cdpUrl, cdpTargetId);

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/bootstrap.js

@@ -547,11 +547,16 @@ async function setupTvOSDriverCache() {
  * Start the tvOS XCTest driver via `xcodebuild test-without-building`.
  * Mirrors startIOSDriver but targets the tvOS xctestrun.
  *
- * On first launch the runner app appears in the foreground, so we press the
- * home button to dismiss it. On subsequent restarts (e.g. health-check recovery)
- * we skip the dismiss to avoid disrupting the user's navigation state.
+ * On first launch the runner app appears in the foreground, displacing whatever
+ * app the user had open. When `restoreFocusAfterLaunch` is set we ask the driver
+ * to re-activate that app once the server is up; otherwise the runner stays in
+ * front and commands like `inspect` run against the wrong target. The driver
+ * falls back to pressing home when no candidate app is found.
+ *
+ * Subsequent restarts (e.g. health-check recovery) skip the restore to avoid
+ * disrupting whatever the user is doing.
  */
-async function startTvOSDriver(deviceId, port = TVOS_BASE_PORT, dismissAfterLaunch = false) {
+async function startTvOSDriver(deviceId, port = TVOS_BASE_PORT, restoreFocusAfterLaunch = false) {
     if (await isPortOpen(port)) {
         (0, verbose_js_1.log)(`tvOS driver already running on port ${port}`);
         return;
@@ -579,13 +584,18 @@ async function startTvOSDriver(deviceId, port = TVOS_BASE_PORT, dismissAfterLaun
         await (0, utils_js_1.sleep)(TVOS_STARTUP_POLL_MS);
         if (await isPortOpen(port)) {
             (0, verbose_js_1.log)(`tvOS driver ready on port ${port}`);
-            if (dismissAfterLaunch) {
+            if (restoreFocusAfterLaunch) {
                 try {
-                    await pressButtonViaDriver(port, 'home');
-                    (0, verbose_js_1.log)('Dismissed tvOS driver app');
+                    const restored = await restoreFocusViaDriver(port);
+                    if (restored) {
+                        (0, verbose_js_1.log)(`Restored tvOS focus to ${restored}`);
+                    }
+                    else {
+                        (0, verbose_js_1.log)('Dismissed tvOS driver app (no previous app to restore)');
+                    }
                 }
                 catch {
-                    (0, verbose_js_1.log)('Could not dismiss tvOS driver app (non-fatal)');
+                    (0, verbose_js_1.log)('Could not restore tvOS focus (non-fatal)');
                 }
             }
             return;
@@ -827,25 +837,39 @@ async function uninstallDriver(deviceId, platform) {
     }
 }
 // ── Helpers ───────────────────────────────────────────────────────────────────
-/** Send a pressButton command directly to the driver HTTP server. */
-function pressButtonViaDriver(port, button) {
+/**
+ * Ask the driver to restore foreground focus to whatever app was active before
+ * the runner launched. Returns the bundle ID that was activated, or null when
+ * the driver fell back to pressing home because no previous app was found.
+ */
+function restoreFocusViaDriver(port) {
     return new Promise((resolve, reject) => {
-        const body = JSON.stringify({ button });
         const options = {
             hostname: '127.0.0.1',
             port,
-            path: '/pressButton',
+            path: '/restoreFocus',
             method: 'POST',
-            headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) },
+            headers: { 'Content-Type': 'application/json', 'Content-Length': 0 },
         };
         const req = http_1.default.request(options, (res) => {
-            res.resume();
-            res.on('end', () => res.statusCode && res.statusCode < 300
-                ? resolve()
-                : reject(new Error(`HTTP ${res.statusCode}`)));
+            const chunks = [];
+            res.on('data', (c) => chunks.push(c));
+            res.on('end', () => {
+                if (!res.statusCode || res.statusCode >= 300) {
+                    reject(new Error(`HTTP ${res.statusCode}`));
+                    return;
+                }
+                try {
+                    const body = Buffer.concat(chunks).toString('utf-8');
+                    const parsed = JSON.parse(body);
+                    resolve(parsed.restoredBundleId ? parsed.restoredBundleId : null);
+                }
+                catch (err) {
+                    reject(err);
+                }
+            });
         });
         req.on('error', reject);
-        req.write(body);
         req.end();
     });
 }

package/dist/drivers/direct-ios-selector.js

@@ -63,6 +63,7 @@ function makeIOSDirectResolver(driver, sel, appIds = []) {
         return {
             centerX: X + Width / 2,
             centerY: Y + Height / 2,
+            bounds: { x: X, y: Y, width: Width, height: Height },
             text: n.label || n.title || n.value || n.placeholderValue || undefined,
             id: n.identifier || undefined,
         };

package/dist/drivers/element-resolver.js

@@ -204,6 +204,7 @@ function findIOSElement(root, sel) {
     return {
         centerX: X + Width / 2,
         centerY: Y + Height / 2,
+        bounds: { x: X, y: Y, width: Width, height: Height },
         text: iosTextOf(node) || undefined,
         id: node.identifier || undefined,
     };
@@ -353,6 +354,7 @@ function findAndroidElement(xml, sel) {
     return {
         centerX: (x1 + x2) / 2,
         centerY: (y1 + y2) / 2,
+        bounds: { x: x1, y: y1, width: x2 - x1, height: y2 - y1 },
         text: androidTextOf(node) || undefined,
         id: node.resourceId || undefined,
     };
@@ -558,6 +560,7 @@ function findWebElement(hierarchy, sel) {
     return {
         centerX: b.x + b.width / 2,
         centerY: b.y + b.height / 2,
+        bounds: { x: b.x, y: b.y, width: b.width, height: b.height },
         text: node.name || undefined,
         id: node.ref || undefined,
     };

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,10 +509,44 @@ 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']);
-            exitCode = await (0, screenshot_js_1.screenshot)(outPath, opts, sessionName, fullPage);
+            const element = rest.join(' ');
+            exitCode = await (0, screenshot_js_1.screenshot)(outPath, opts, sessionName, fullPage, element, {
+                id: argv['id'],
+                text: argv['text'],
+                index: argv['index'] !== undefined ? Number(argv['index']) : undefined,
+                margin: argv['margin'] !== undefined ? Number(argv['margin']) : undefined,
+                focused: argv['focused'] !== undefined ? argv['focused'] : undefined,
+                enabled: argv['enabled'] !== undefined ? argv['enabled'] : undefined,
+                checked: argv['checked'] !== undefined ? argv['checked'] : undefined,
+                selected: argv['selected'] !== undefined ? argv['selected'] : undefined,
+                below: argv['below'],
+                above: argv['above'],
+                leftOf: argv['left-of'],
+                rightOf: argv['right-of'],
+            });
             break;
         }
         case 'capture-ui': {

package/dist/png-crop.js

@@ -0,0 +1,191 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readPngDimensions = readPngDimensions;
+exports.cropPng = cropPng;
+/**
+ * Minimal PNG cropper — decodes 8-bit RGB / RGBA / grayscale / grayscale+alpha
+ * PNGs, crops to a rect, re-encodes with filter type 0 (None).
+ *
+ * Used by `take-screenshot --id/--text/<query>` to return only the pixels
+ * inside a resolved element's bounds.
+ */
+const zlib_1 = __importDefault(require("zlib"));
+const SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+const CRC_TABLE = (() => {
+    const table = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+        let c = n;
+        for (let k = 0; k < 8; k++)
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        table[n] = c >>> 0;
+    }
+    return table;
+})();
+function crc32(buf) {
+    let c = 0xffffffff;
+    for (let i = 0; i < buf.length; i++)
+        c = CRC_TABLE[(c ^ buf[i]) & 0xff] ^ (c >>> 8);
+    return (c ^ 0xffffffff) >>> 0;
+}
+/** Read width/height from a PNG IHDR chunk. Throws if `buf` is not a PNG. */
+function readPngDimensions(buf) {
+    if (buf.length < 24 || !SIGNATURE.equals(buf.subarray(0, 8))) {
+        throw new Error('not a PNG');
+    }
+    return { width: buf.readUInt32BE(16), height: buf.readUInt32BE(20) };
+}
+function bytesPerPixel(colorType) {
+    switch (colorType) {
+        case 0:
+            return 1; // grayscale
+        case 2:
+            return 3; // RGB
+        case 3:
+            return 1; // palette (unsupported below)
+        case 4:
+            return 2; // grayscale + alpha
+        case 6:
+            return 4; // RGBA
+        default:
+            throw new Error(`unsupported PNG color type ${colorType}`);
+    }
+}
+function paeth(a, b, c) {
+    const p = a + b - c;
+    const pa = Math.abs(p - a);
+    const pb = Math.abs(p - b);
+    const pc = Math.abs(p - c);
+    if (pa <= pb && pa <= pc)
+        return a;
+    if (pb <= pc)
+        return b;
+    return c;
+}
+function unfilter(filtered, w, h, bpp) {
+    const stride = w * bpp;
+    const out = Buffer.alloc(stride * h);
+    let inOff = 0;
+    for (let y = 0; y < h; y++) {
+        const filter = filtered[inOff++];
+        const rowOff = y * stride;
+        for (let x = 0; x < stride; x++) {
+            const raw = filtered[inOff++];
+            const left = x >= bpp ? out[rowOff + x - bpp] : 0;
+            const up = y > 0 ? out[rowOff - stride + x] : 0;
+            const upLeft = x >= bpp && y > 0 ? out[rowOff - stride + x - bpp] : 0;
+            let v;
+            switch (filter) {
+                case 0:
+                    v = raw;
+                    break;
+                case 1:
+                    v = raw + left;
+                    break;
+                case 2:
+                    v = raw + up;
+                    break;
+                case 3:
+                    v = raw + ((left + up) >> 1);
+                    break;
+                case 4:
+                    v = raw + paeth(left, up, upLeft);
+                    break;
+                default:
+                    throw new Error(`unsupported PNG filter ${filter}`);
+            }
+            out[rowOff + x] = v & 0xff;
+        }
+    }
+    return out;
+}
+function writeChunk(out, type, data) {
+    const len = Buffer.alloc(4);
+    len.writeUInt32BE(data.length, 0);
+    const typeBuf = Buffer.from(type, 'ascii');
+    const crcInput = Buffer.concat([typeBuf, data]);
+    const crc = Buffer.alloc(4);
+    crc.writeUInt32BE(crc32(crcInput), 0);
+    out.push(len, typeBuf, data, crc);
+}
+/**
+ * Crop a PNG buffer to the given rect. Coordinates are in PNG pixel space;
+ * `x`/`y`/`width`/`height` are clamped to the PNG canvas before cropping.
+ * Throws if the rect lies fully outside the canvas.
+ */
+function cropPng(buf, rect) {
+    if (buf.length < 8 || !SIGNATURE.equals(buf.subarray(0, 8))) {
+        throw new Error('not a PNG');
+    }
+    let off = 8;
+    let ihdr = null;
+    const idatParts = [];
+    while (off < buf.length) {
+        const len = buf.readUInt32BE(off);
+        off += 4;
+        const type = buf.subarray(off, off + 4).toString('ascii');
+        off += 4;
+        const data = buf.subarray(off, off + len);
+        off += len;
+        off += 4; // CRC
+        if (type === 'IHDR') {
+            ihdr = {
+                width: data.readUInt32BE(0),
+                height: data.readUInt32BE(4),
+                bitDepth: data.readUInt8(8),
+                colorType: data.readUInt8(9),
+            };
+        }
+        else if (type === 'IDAT') {
+            idatParts.push(data);
+        }
+        else if (type === 'IEND') {
+            break;
+        }
+    }
+    if (!ihdr)
+        throw new Error('PNG missing IHDR');
+    if (ihdr.bitDepth !== 8) {
+        throw new Error(`unsupported PNG bit depth ${ihdr.bitDepth} (only 8 supported)`);
+    }
+    if (ihdr.colorType === 3) {
+        throw new Error('palette PNGs are not supported for cropping');
+    }
+    const bpp = bytesPerPixel(ihdr.colorType);
+    // Clamp crop rect to canvas bounds
+    const cx = Math.max(0, Math.min(Math.floor(rect.x), ihdr.width));
+    const cy = Math.max(0, Math.min(Math.floor(rect.y), ihdr.height));
+    const cx2 = Math.max(0, Math.min(Math.floor(rect.x + rect.width), ihdr.width));
+    const cy2 = Math.max(0, Math.min(Math.floor(rect.y + rect.height), ihdr.height));
+    const cw = cx2 - cx;
+    const ch = cy2 - cy;
+    if (cw <= 0 || ch <= 0) {
+        throw new Error('crop rect is outside the screenshot canvas');
+    }
+    const filtered = zlib_1.default.inflateSync(Buffer.concat(idatParts));
+    const raw = unfilter(filtered, ihdr.width, ihdr.height, bpp);
+    const srcStride = ihdr.width * bpp;
+    const dstStride = cw * bpp;
+    // New filtered scanlines with filter byte 0 (None) prefix.
+    const filteredOut = Buffer.alloc(ch * (dstStride + 1));
+    for (let y = 0; y < ch; y++) {
+        filteredOut[y * (dstStride + 1)] = 0;
+        raw.copy(filteredOut, y * (dstStride + 1) + 1, (cy + y) * srcStride + cx * bpp, (cy + y) * srcStride + cx * bpp + dstStride);
+    }
+    const idat = zlib_1.default.deflateSync(filteredOut);
+    const chunks = [SIGNATURE];
+    const ihdrData = Buffer.alloc(13);
+    ihdrData.writeUInt32BE(cw, 0);
+    ihdrData.writeUInt32BE(ch, 4);
+    ihdrData.writeUInt8(ihdr.bitDepth, 8);
+    ihdrData.writeUInt8(ihdr.colorType, 9);
+    ihdrData.writeUInt8(0, 10); // compression
+    ihdrData.writeUInt8(0, 11); // filter method
+    ihdrData.writeUInt8(0, 12); // interlace
+    writeChunk(chunks, 'IHDR', ihdrData);
+    writeChunk(chunks, 'IDAT', idat);
+    writeChunk(chunks, 'IEND', Buffer.alloc(0));
+    return Buffer.concat(chunks);
+}

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.19.0",
   "description": "CLI tool for mobile app interactions — optimized for AI agents",
   "license": "MIT",
   "repository": {