@houwert/conductor 0.5.0 → 0.6.0

package/dist/device-picker.js

@@ -11,9 +11,14 @@ const list_devices_js_1 = require("./commands/list-devices.js");
  * - 1 device  → returns it automatically
  * - N devices + TTY → shows a numbered picker
  * - N devices + no TTY → returns undefined (caller should error)
+ *
+ * When `platform` is provided, only devices matching that platform are considered.
  */
-async function pickDevice() {
-    const devices = await (0, list_devices_js_1.discoverBootedDevices)();
+async function pickDevice(platform) {
+    let devices = await (0, list_devices_js_1.discoverBootedDevices)();
+    if (platform) {
+        devices = devices.filter((d) => d.platform === platform.toLowerCase());
+    }
     if (devices.length === 0)
         return undefined;
     if (devices.length === 1)

package/dist/drivers/bootstrap.js

@@ -15,6 +15,12 @@ exports.startTvOSDriver = startTvOSDriver;
 exports.stopTvOSDriver = stopTvOSDriver;
 exports.startAndroidDriver = startAndroidDriver;
 exports.stopAndroidDriver = stopAndroidDriver;
+exports.webBrowserName = webBrowserName;
+exports.generateWebSessionId = generateWebSessionId;
+exports.isUnqualifiedWebId = isUnqualifiedWebId;
+exports.isPlaywrightBrowserInstalled = isPlaywrightBrowserInstalled;
+exports.ensurePlaywrightBrowser = ensurePlaywrightBrowser;
+exports.stopWebDriver = stopWebDriver;
 exports.uninstallDriver = uninstallDriver;
 /**
  * Driver lifecycle manager.
@@ -27,6 +33,7 @@ exports.uninstallDriver = uninstallDriver;
  * drivers/ios/ — no separate Conductor/JVM installation required.
  */
 const child_process_1 = require("child_process");
+const crypto_1 = __importDefault(require("crypto"));
 const http_1 = __importDefault(require("http"));
 const net_1 = __importDefault(require("net"));
 const os_1 = __importDefault(require("os"));
@@ -39,6 +46,11 @@ const _platformCache = new Map();
 async function detectPlatform(deviceId) {
     if (_platformCache.has(deviceId))
         return _platformCache.get(deviceId);
+    // Web browser: "web", "web:chromium", "web:firefox", "web:webkit"
+    if (deviceId === 'web' || deviceId.startsWith('web:')) {
+        _platformCache.set(deviceId, 'web');
+        return 'web';
+    }
     // Check if it looks like an iOS/tvOS simulator UUID (8-4-4-4-12 hex chars)
     const iosUuidRe = /^[0-9A-F]{8}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{12}$/i;
     if (iosUuidRe.test(deviceId)) {
@@ -68,6 +80,7 @@ async function detectPlatform(deviceId) {
 const IOS_BASE_PORT = 1075;
 const TVOS_BASE_PORT = 2075;
 const ANDROID_BASE_PORT = 3763;
+const WEB_BASE_PORT = 4075;
 const PORT_FILE = path_1.default.join(os_1.default.homedir(), '.conductor', 'ports.json');
 const PORT_LOCK = PORT_FILE + '.lock';
 const PORT_LOCK_TIMEOUT_MS = 5000;
@@ -81,6 +94,7 @@ function readPortState() {
             nextIosPort: IOS_BASE_PORT,
             nextTvosPort: TVOS_BASE_PORT,
             nextAndroidPort: ANDROID_BASE_PORT,
+            nextWebPort: WEB_BASE_PORT,
         };
     }
 }
@@ -124,9 +138,11 @@ async function getDriverPort(platform, deviceId) {
         if (state.assignments[deviceId] !== undefined) {
             return state.assignments[deviceId];
         }
-        // Ensure tvos counter is initialised for port files created before tvOS support
+        // Ensure counters are initialised for port files created before new platform support
         if (state.nextTvosPort === undefined)
             state.nextTvosPort = TVOS_BASE_PORT;
+        if (state.nextWebPort === undefined)
+            state.nextWebPort = WEB_BASE_PORT;
         let port;
         if (platform === 'ios') {
             port = state.nextIosPort++;
@@ -134,6 +150,9 @@ async function getDriverPort(platform, deviceId) {
         else if (platform === 'tvos') {
             port = state.nextTvosPort++;
         }
+        else if (platform === 'web') {
+            port = state.nextWebPort++;
+        }
         else {
             port = state.nextAndroidPort++;
         }
@@ -480,6 +499,110 @@ async function stopAndroidDriver(deviceId, port = ANDROID_BASE_PORT) {
     ]).catch(() => { });
     await spawnAndWait('adb', ['-s', deviceId, 'forward', '--remove', `tcp:${port}`]).catch(() => { });
 }
+// ── Web bootstrap ────────────────────────────────────────────────────────────
+/**
+ * Extract the browser name from a web device ID.
+ * "web" → "chromium", "web:firefox" → "firefox", "web:webkit" → "webkit"
+ *
+ * Also handles instance-qualified IDs:
+ * "web:chromium:abc1" → "chromium", "web:firefox:abc1" → "firefox"
+ */
+function webBrowserName(deviceId) {
+    if (deviceId.startsWith('web:')) {
+        const browser = deviceId.slice(4).split(':')[0];
+        if (browser === 'firefox' || browser === 'webkit')
+            return browser;
+    }
+    return 'chromium';
+}
+/**
+ * Generate a unique web session ID for parallel browser instances.
+ * Format: "web:<browser>:<8-hex-char-id>"
+ */
+function generateWebSessionId(browserName = 'chromium') {
+    const id = crypto_1.default.randomBytes(4).toString('hex');
+    return `web:${browserName}:${id}`;
+}
+/**
+ * True when the device ID refers to a web browser but does NOT include
+ * an instance qualifier — i.e. "web" or "web:<browser>" but not "web:<browser>:<id>".
+ */
+function isUnqualifiedWebId(deviceId) {
+    if (deviceId === 'web')
+        return true;
+    if (!deviceId.startsWith('web:'))
+        return false;
+    return deviceId.split(':').length === 2;
+}
+/**
+ * Check whether a Playwright browser is installed for the current playwright-core version.
+ * Returns true if the executable exists, false otherwise.
+ */
+function isPlaywrightBrowserInstalled(browserName) {
+    try {
+        // Dynamic import to avoid pulling playwright-core into every code path
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const pw = require('playwright-core');
+        const execPath = pw[browserName].executablePath();
+        return fs_1.default.existsSync(execPath);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Install a Playwright browser if not already present.
+ * Shells out to `npx playwright-core install <browser>` which downloads the
+ * version-matched browser binary to the default cache (~/.cache/ms-playwright).
+ */
+async function ensurePlaywrightBrowser(browserName, logger = verbose_js_1.log) {
+    if (isPlaywrightBrowserInstalled(browserName)) {
+        logger(`Playwright ${browserName} is already installed`);
+        return;
+    }
+    logger(`Installing Playwright ${browserName} browser...`);
+    // Use the playwright-core CLI to install the browser.
+    // Resolve the playwright-core binary from node_modules.
+    const pwCoreBin = path_1.default.join(path_1.default.dirname(require.resolve('playwright-core/package.json')), 'cli.js');
+    await new Promise((resolve, reject) => {
+        const proc = (0, child_process_1.spawn)(process.execPath, [pwCoreBin, 'install', browserName], {
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        let stderr = '';
+        proc.stderr?.on('data', (chunk) => {
+            stderr += chunk.toString();
+        });
+        proc.stdout?.on('data', (chunk) => {
+            const line = chunk.toString().trim();
+            if (line)
+                logger(line);
+        });
+        proc.on('close', (code) => {
+            if (code === 0) {
+                logger(`Playwright ${browserName} installed successfully`);
+                resolve();
+            }
+            else {
+                reject(new Error(`Failed to install Playwright ${browserName} (exit ${code}).\n${stderr.trim()}\n` +
+                    `You can install manually: npx playwright-core install ${browserName}`));
+            }
+        });
+        proc.on('error', (err) => {
+            reject(new Error(`Failed to run Playwright installer: ${err.message}\n` +
+                `You can install manually: npx playwright-core install ${browserName}`));
+        });
+    });
+}
+/**
+ * Stop the web driver by sending a shutdown request to its HTTP server.
+ */
+async function stopWebDriver(port) {
+    return new Promise((resolve) => {
+        const req = http_1.default.request({ hostname: '127.0.0.1', port, path: '/shutdown', method: 'POST' }, () => resolve());
+        req.on('error', () => resolve());
+        req.end();
+    });
+}
 /**
  * Uninstall the Conductor driver app(s) from the device.
  */

package/dist/drivers/element-resolver.js

@@ -5,10 +5,11 @@ exports.parseAndroidHierarchy = parseAndroidHierarchy;
 exports.findAndroidElement = findAndroidElement;
 exports.inspectIOSToText = inspectIOSToText;
 exports.inspectAndroidToText = inspectAndroidToText;
+exports.findWebElement = findWebElement;
+exports.inspectWebToText = inspectWebToText;
 const verbose_js_1 = require("../verbose.js");
 // XCUIElementType rawValues that represent interactive controls.
-// Mirrors Maestro's clickableFirst() behaviour for iOS, where clickable is not
-// exposed in the AXElement — we sort by element type instead.
+// Approximates “prefer clickable” when sorting, since AXElement does not expose clickable.
 const IOS_INTERACTIVE_TYPES = new Set([
     9, // Button
     23, // Slider
@@ -46,37 +47,65 @@ function collectIOSElements(node, results) {
 function iosTextOf(node) {
     return node.label || node.title || node.value || node.placeholderValue || '';
 }
-function matchesText(candidate, query) {
-    if (!query)
-        return false;
-    if (candidate === query)
-        return true;
-    if (candidate.toLowerCase() === query.toLowerCase())
-        return true;
-    // fuzzy: .*query.* regex
+function iosTextMatchFields(node) {
+    return [node.label, node.title, node.value, node.placeholderValue];
+}
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function toRegexSafe(pattern) {
     try {
-        const re = new RegExp(`.*${escapeRegex(query)}.*`, 'i');
-        return re.test(candidate);
+        return new RegExp(pattern, 'ims');
     }
     catch {
+        return new RegExp(escapeRegex(pattern), 'ims');
+    }
+}
+function regexMatchesEntireString(regex, value) {
+    const anchored = new RegExp(`^(?:${regex.source})$`, regex.flags);
+    return anchored.test(value);
+}
+/** Entire attribute value must match the pattern; newlines are normalized to spaces for a second pass. */
+function matchPatternAgainstTextField(pattern, value) {
+    if (value == null || value === '')
         return false;
+    const re = toRegexSafe(pattern);
+    const stripped = value.replace(/\n/g, ' ');
+    return (regexMatchesEntireString(re, value) ||
+        pattern === value ||
+        regexMatchesEntireString(re, stripped) ||
+        pattern === stripped);
+}
+function matchPatternAgainstAnyTextField(pattern, fields) {
+    for (const f of fields) {
+        if (f != null && f !== '' && matchPatternAgainstTextField(pattern, f))
+            return true;
     }
+    return false;
 }
-function escapeRegex(s) {
-    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+function substringAfterLastSlash(s) {
+    const i = s.lastIndexOf('/');
+    return i === -1 ? s : s.slice(i + 1);
+}
+function matchPatternAgainstElementId(pattern, value) {
+    if (value == null || value === '')
+        return false;
+    return (matchPatternAgainstTextField(pattern, value) ||
+        matchPatternAgainstTextField(pattern, substringAfterLastSlash(value)));
 }
 function matchesIOSElement(node, sel) {
     if (sel.query) {
-        const text = iosTextOf(node);
-        if (!matchesText(text, sel.query) && !matchesText(node.identifier, sel.query))
+        const textOk = matchPatternAgainstAnyTextField(sel.query, iosTextMatchFields(node));
+        const idOk = matchPatternAgainstElementId(sel.query, node.identifier);
+        if (!textOk && !idOk)
             return false;
     }
     if (sel.text) {
-        if (!matchesText(iosTextOf(node), sel.text))
+        if (!matchPatternAgainstAnyTextField(sel.text, iosTextMatchFields(node)))
             return false;
     }
     if (sel.id) {
-        if (!matchesText(node.identifier, sel.id))
+        if (!matchPatternAgainstElementId(sel.id, node.identifier))
             return false;
     }
     // State attributes — only match fields that exist on AXElement
@@ -91,10 +120,8 @@ function matchesIOSElement(node, sel) {
     return true;
 }
 /**
- * Mirrors Maestro's deepestMatchingElement(): for each branch of the tree,
- * return matching nodes only from the deepest level that has a match.
- * This prevents parent wrapper nodes that inherit their child's accessibility
- * label (common in React Native) from appearing as separate candidates.
+ * Deepest match per branch: prefer matches in descendants so parent wrappers that only
+ * duplicate a child label (e.g. React Native) do not appear as duplicate tap targets.
  */
 function deepestMatchingIOSElements(node, pred) {
     // Recurse into children first — deepest match wins over ancestor
@@ -150,14 +177,14 @@ function findIOSElement(root, sel) {
             `type=${n.elementType}${interactive ? ' (interactive)' : ''}`);
     });
     if (sel.index !== undefined) {
-        // Mirror Maestro's INDEX_COMPARATOR: sort top-to-bottom, then left-to-right
+        // Sort top-to-bottom, then left-to-right when index is set
         matches = [...matches].sort((a, b) => {
             const dy = a.frame.Y - b.frame.Y;
             return dy !== 0 ? dy : a.frame.X - b.frame.X;
         });
     }
     else {
-        // Prefer interactive element types (approximation of Maestro's clickableFirst for iOS)
+        // Prefer interactive element types when no explicit index
         matches = [...matches].sort((a, b) => Number(IOS_INTERACTIVE_TYPES.has(b.elementType)) -
             Number(IOS_INTERACTIVE_TYPES.has(a.elementType)));
     }
@@ -237,17 +264,22 @@ function parseAndroidHierarchy(xml) {
 function androidTextOf(n) {
     return n.text || n.contentDesc || '';
 }
+function androidTextMatchFields(n) {
+    return [n.text, n.contentDesc, n.hintText];
+}
 function matchesAndroidNode(n, sel) {
     if (sel.query) {
-        if (!matchesText(androidTextOf(n), sel.query) && !matchesText(n.resourceId, sel.query))
+        const textOk = matchPatternAgainstAnyTextField(sel.query, androidTextMatchFields(n));
+        const idOk = matchPatternAgainstElementId(sel.query, n.resourceId);
+        if (!textOk && !idOk)
             return false;
     }
     if (sel.text) {
-        if (!matchesText(androidTextOf(n), sel.text))
+        if (!matchPatternAgainstAnyTextField(sel.text, androidTextMatchFields(n)))
             return false;
     }
     if (sel.id) {
-        if (!matchesText(n.resourceId, sel.id))
+        if (!matchPatternAgainstElementId(sel.id, n.resourceId))
             return false;
     }
     if (sel.enabled !== undefined && n.enabled !== sel.enabled)
@@ -301,9 +333,7 @@ function findAndroidElement(xml, sel) {
             `bounds=[${x1},${y1}][${x2},${y2}]` +
             `${n.clickable ? ' (clickable)' : ''}`);
     });
-    // Mirror Maestro's clickableFirst(): when no index is specified, prefer
-    // clickable nodes so a text label shared by a Button and a plain TextView
-    // resolves to the button, matching Maestro's GraalVM behaviour.
+    // When no index is specified, prefer clickable nodes so shared labels resolve to controls.
     if (sel.index === undefined) {
         matches = [...matches].sort((a, b) => Number(b.clickable) - Number(a.clickable));
     }
@@ -379,3 +409,184 @@ function inspectAndroidToText(xml) {
     })
         .join('\n');
 }
+// ── Web: ARIA snapshot tree traversal ───────────────────────────────────────
+// ARIA roles that represent interactive controls — mirrors IOS_INTERACTIVE_TYPES
+const WEB_INTERACTIVE_ROLES = new Set([
+    'button',
+    'link',
+    'textbox',
+    'searchbox',
+    'checkbox',
+    'radio',
+    'switch',
+    'slider',
+    'spinbutton',
+    'combobox',
+    'listbox',
+    'option',
+    'menuitem',
+    'menuitemcheckbox',
+    'menuitemradio',
+    'tab',
+]);
+/** Collect all visible (has bounds) leaf/interactive elements from a WebElement tree. */
+function collectWebElements(nodes, results) {
+    for (const node of nodes) {
+        const visible = node.bounds && node.bounds.width > 0 && node.bounds.height > 0;
+        if (visible) {
+            const hasContent = !!(node.name || node.ref);
+            const isLeaf = !node.children || node.children.length === 0;
+            if (hasContent || isLeaf) {
+                results.push(node);
+            }
+        }
+        if (node.children) {
+            collectWebElements(node.children, results);
+        }
+    }
+}
+function matchesWebElement(node, sel) {
+    if (sel.query) {
+        const textOk = matchPatternAgainstAnyTextField(sel.query, [node.name]);
+        const idOk = matchPatternAgainstElementId(sel.query, node.ref);
+        if (!textOk && !idOk)
+            return false;
+    }
+    if (sel.text) {
+        if (!matchPatternAgainstAnyTextField(sel.text, [node.name]))
+            return false;
+    }
+    if (sel.id) {
+        if (!matchPatternAgainstElementId(sel.id, node.ref))
+            return false;
+    }
+    if (sel.enabled !== undefined && node.enabled !== sel.enabled)
+        return false;
+    if (sel.checked !== undefined && node.checked !== sel.checked)
+        return false;
+    if (sel.focused !== undefined && node.focused !== sel.focused)
+        return false;
+    if (sel.selected !== undefined && node.selected !== sel.selected)
+        return false;
+    return true;
+}
+/**
+ * Deepest matching elements — same logic as iOS to avoid parent wrapper duplicates.
+ */
+function deepestMatchingWebElements(nodes, pred) {
+    const results = [];
+    for (const node of nodes) {
+        const childMatches = node.children ? deepestMatchingWebElements(node.children, pred) : [];
+        if (childMatches.length > 0) {
+            results.push(...childMatches);
+        }
+        else if (node.bounds && node.bounds.width > 0 && node.bounds.height > 0 && pred(node)) {
+            results.push(node);
+        }
+    }
+    return results;
+}
+function findWebElement(hierarchy, sel) {
+    // Resolve reference frame for relative-position selectors
+    let refBounds = null;
+    const relSel = sel.below ?? sel.above ?? sel.leftOf ?? sel.rightOf;
+    if (relSel) {
+        const allNodes = [];
+        collectWebElements(hierarchy.elements, allNodes);
+        const ref = allNodes.find((n) => matchesWebElement(n, relSel));
+        if (!ref?.bounds)
+            return null;
+        refBounds = ref.bounds;
+    }
+    // Find deepest matching nodes
+    let matches = deepestMatchingWebElements(hierarchy.elements, (n) => matchesWebElement(n, sel));
+    // Apply relative position filter
+    if (refBounds) {
+        const refBottom = refBounds.y + refBounds.height;
+        const refRight = refBounds.x + refBounds.width;
+        if (sel.below) {
+            matches = matches.filter((n) => n.bounds && n.bounds.y >= refBottom);
+        }
+        else if (sel.above) {
+            matches = matches.filter((n) => n.bounds && n.bounds.y + n.bounds.height <= refBounds.y);
+        }
+        else if (sel.leftOf) {
+            matches = matches.filter((n) => n.bounds && n.bounds.x + n.bounds.width <= refBounds.x);
+        }
+        else if (sel.rightOf) {
+            matches = matches.filter((n) => n.bounds && n.bounds.x >= refRight);
+        }
+    }
+    // Filter to elements that have bounding boxes (visible and measurable)
+    matches = matches.filter((n) => n.bounds && n.bounds.width > 0 && n.bounds.height > 0);
+    if (matches.length === 0) {
+        (0, verbose_js_1.log)(`[Web] no candidates matched selector`, sel);
+        return null;
+    }
+    (0, verbose_js_1.log)(`[Web] ${matches.length} candidate(s):`);
+    matches.forEach((n, i) => {
+        const b = n.bounds;
+        const interactive = WEB_INTERACTIVE_ROLES.has(n.role);
+        (0, verbose_js_1.log)(`  [${i}] text="${n.name}" ref="${n.ref}" role="${n.role}" ` +
+            `bounds=[${Math.round(b.x)},${Math.round(b.y)}][${Math.round(b.x + b.width)},${Math.round(b.y + b.height)}]` +
+            `${interactive ? ' (interactive)' : ''}`);
+    });
+    if (sel.index !== undefined) {
+        // Sort top-to-bottom, then left-to-right
+        matches = [...matches].sort((a, b) => {
+            const dy = a.bounds.y - b.bounds.y;
+            return dy !== 0 ? dy : a.bounds.x - b.bounds.x;
+        });
+    }
+    else {
+        // Prefer interactive roles
+        matches = [...matches].sort((a, b) => Number(WEB_INTERACTIVE_ROLES.has(b.role)) - Number(WEB_INTERACTIVE_ROLES.has(a.role)));
+    }
+    const idx = sel.index ?? 0;
+    const node = matches[idx < 0 ? matches.length + idx : idx];
+    if (!node) {
+        (0, verbose_js_1.log)(`[Web] index ${idx} out of range (${matches.length} candidates)`);
+        return null;
+    }
+    const b = node.bounds;
+    (0, verbose_js_1.log)(`[Web] chose [${idx}] text="${node.name}" ref="${node.ref}" role="${node.role}" ` +
+        `bounds=[${Math.round(b.x)},${Math.round(b.y)}][${Math.round(b.x + b.width)},${Math.round(b.y + b.height)}] ` +
+        `→ tap (${Math.round(b.x + b.width / 2)}, ${Math.round(b.y + b.height / 2)})`);
+    return {
+        centerX: b.x + b.width / 2,
+        centerY: b.y + b.height / 2,
+        text: node.name || undefined,
+        id: node.ref || undefined,
+    };
+}
+/**
+ * Format web ARIA hierarchy into LLM-optimized text.
+ */
+function inspectWebToText(hierarchy) {
+    const lines = [];
+    visitWeb(hierarchy.elements, lines, 0);
+    return lines.join('\n');
+}
+function visitWeb(nodes, lines, depth) {
+    for (const node of nodes) {
+        const parts = [];
+        parts.push(node.role);
+        if (node.name)
+            parts.push(`"${node.name}"`);
+        if (node.ref)
+            parts.push(`ref=${node.ref}`);
+        if (node.bounds) {
+            const b = node.bounds;
+            parts.push(`bounds=[${Math.round(b.x)},${Math.round(b.y)}][${Math.round(b.x + b.width)},${Math.round(b.y + b.height)}]`);
+        }
+        if (!node.enabled)
+            parts.push('disabled');
+        // Only output nodes that have content
+        if (node.name || node.ref || (node.bounds && (!node.children || node.children.length === 0))) {
+            lines.push(`${'  '.repeat(depth)}${parts.join(' ')}`);
+        }
+        if (node.children) {
+            visitWeb(node.children, lines, depth + 1);
+        }
+    }
+}