@leera.io/qa-runner 1.0.0

package/dist/src/drivers/webdriver/locate.js

@@ -0,0 +1,136 @@
+import { setTimeout as sleep } from 'node:timers/promises';
+/** Android locator keys (plan §3); exactly one is set on a target. */
+export const ANDROID_LOCATORS = ['id', 'desc', 'text', 'test_id', 'class', 'uiautomator', 'xpath'];
+/** Escapes a Java string literal inside a UiSelector expression. */
+export function escapeUiSelector(value) {
+    return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+/** Escapes a value for a Java regex (`resourceIdMatches`, `classNameMatches`). */
+export function escapeJavaRegex(value) {
+    return value.replace(/[\\^$.|?*+()[\]{}]/g, '\\$&');
+}
+function ui(expression) {
+    return { using: '-android uiautomator', value: `new UiSelector().${expression}` };
+}
+/**
+ * Maps one android target (without fallbacks/nth) to the selectors to try, in order.
+ * `render` resolves `{{placeholders}}` in the value first.
+ *
+ * - `id`: `com.acme:id/login` exactly; a bare `login` matches `<any package>:id/login`.
+ * - `desc`: exact content-description unless `exact: false` (then contains).
+ * - `text`: contains unless `exact: true`.
+ * - `test_id` (React Native / Expo `testID`): resource-id equal to the value, then
+ *   `<package>:id/<value>`, then content-description (accessibility id).
+ * - `class`: full class name, or a simple name matched as `….Name`.
+ * - `uiautomator`: a UiSelector expression, used as is.
+ * - `xpath`: used as is.
+ */
+export function androidSelectors(target, render = (t) => t) {
+    if (target.id !== undefined) {
+        const id = render(target.id);
+        if (id.includes(':id/'))
+            return [ui(`resourceId("${escapeUiSelector(id)}")`)];
+        return [ui(`resourceIdMatches("${escapeUiSelector(`.*:id/${escapeJavaRegex(id)}`)}")`)];
+    }
+    if (target.desc !== undefined) {
+        const desc = escapeUiSelector(render(target.desc));
+        return [ui(target.exact === false ? `descriptionContains("${desc}")` : `description("${desc}")`)];
+    }
+    if (target.text !== undefined) {
+        const text = escapeUiSelector(render(target.text));
+        return [ui(target.exact === true ? `text("${text}")` : `textContains("${text}")`)];
+    }
+    if (target.test_id !== undefined) {
+        const raw = render(target.test_id);
+        const value = escapeUiSelector(raw);
+        return [
+            ui(`resourceId("${value}")`),
+            ui(`resourceIdMatches("${escapeUiSelector(`.*:id/${escapeJavaRegex(raw)}`)}")`),
+            { using: 'accessibility id', value: raw },
+        ];
+    }
+    if (target.class !== undefined) {
+        const cls = render(target.class);
+        if (cls.includes('.'))
+            return [ui(`className("${escapeUiSelector(cls)}")`)];
+        return [ui(`classNameMatches("${escapeUiSelector(`.*\\.${escapeJavaRegex(cls)}`)}")`)];
+    }
+    if (target.uiautomator !== undefined) {
+        const expression = render(target.uiautomator).trim();
+        return [{ using: '-android uiautomator', value: expression }];
+    }
+    if (target.xpath !== undefined)
+        return [{ using: 'xpath', value: render(target.xpath) }];
+    const named = Object.keys(target).filter((key) => !['exact', 'nth', 'fallbacks', 'locate'].includes(key));
+    throw new Error(named.length > 0
+        ? `'${named[0]}' is not an android locator; use one of ${ANDROID_LOCATORS.join(', ')}`
+        : 'the target names no locator');
+}
+export function describeAndroidTarget(target) {
+    if (target.desc !== undefined)
+        return `element described "${target.desc}"`;
+    if (target.id !== undefined)
+        return `id "${target.id}"`;
+    if (target.text !== undefined)
+        return `text "${target.text}"`;
+    if (target.test_id !== undefined)
+        return `test id "${target.test_id}"`;
+    if (target.class !== undefined)
+        return `class ${target.class}`;
+    if (target.uiautomator !== undefined)
+        return `UiSelector ${target.uiautomator}`;
+    if (target.xpath !== undefined)
+        return `xpath ${target.xpath}`;
+    return 'element';
+}
+export function elementIdOf(reference) {
+    if (reference && typeof reference === 'object') {
+        for (const [key, value] of Object.entries(reference)) {
+            if ((key === 'element-6066-11e4-a52e-4f735466cecf' || key === 'element-6066-11e4-a52f-4ce4f6d4b2fb' || key === 'ELEMENT') && typeof value === 'string')
+                return value;
+        }
+    }
+    throw new Error('the driver returned no element reference');
+}
+/** Elements matching one target (no fallbacks), in document order. */
+export async function findAll(client, target, render) {
+    for (const selector of androidSelectors(target, render)) {
+        const found = await client.findElements(selector.using, selector.value).catch((error) => {
+            const message = error instanceof Error ? error.message : String(error);
+            // An invalid UiSelector/xpath is the script's problem, not a missing element.
+            if (/invalid selector|InvalidSelector|could not parse|UiSelector/i.test(message) && !/no such element/i.test(message))
+                throw error;
+            return [];
+        });
+        if (found.length > 0)
+            return found.map(elementIdOf);
+    }
+    return [];
+}
+/** Candidates in order: the target itself, then its fallbacks. */
+export function candidates(target) {
+    const { fallbacks, ...primary } = target;
+    return [primary, ...(fallbacks ?? []).map(({ fallbacks: _nested, ...rest }) => rest)];
+}
+/** One pass over the target and its fallbacks; null when nothing matches (at `nth`). */
+export async function locateOnce(client, target, render) {
+    for (const candidate of candidates(target)) {
+        const ids = await findAll(client, candidate, render);
+        const nth = candidate.nth ?? 0;
+        if (ids.length > nth)
+            return { elementId: ids[nth], target: candidate, count: ids.length };
+    }
+    return null;
+}
+/** Polls until the target (or a fallback) matches or `timeoutMs` passes. */
+export async function locate(client, target, timeoutMs, render, pollMs = 300) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        const found = await locateOnce(client, target, render);
+        if (found)
+            return found;
+        if (Date.now() >= deadline)
+            return null;
+        await sleep(pollMs);
+    }
+}

package/dist/src/drivers/webdriver/native-actions.js

@@ -0,0 +1,175 @@
+import { setTimeout as sleep } from 'node:timers/promises';
+import { clip, expectWithin, matches, verb } from '../common.js';
+import { NotFound, Unsupported } from '../driver.js';
+import { parseDesktopKey } from './desktop-keys.js';
+import { nativeFindAll, nativeLocate } from './native-locate.js';
+import { webdriverMessage } from './session.js';
+/**
+ * Native desktop DSL actions (contracts §M) shared by the Mac2 and Windows drivers. The app
+ * lifecycle actions (`launch`, `terminate`, `focus_window`) are the drivers' own.
+ */
+export const NATIVE_DESKTOP_ACTIONS = [
+    'launch',
+    'terminate',
+    'focus_window',
+    'click',
+    'double_click',
+    'right_click',
+    'hover',
+    'type',
+    'clear',
+    'press',
+    'check',
+    'uncheck',
+    'select_option',
+    'wait',
+    'screenshot',
+    'wait_for',
+    'expect_visible',
+    'expect_hidden',
+    'expect_text',
+];
+function requireTarget(action) {
+    if (!action.target)
+        throw new Error(`'${action.type}' needs a target`);
+    return action.target;
+}
+async function element(ctx, target, timeoutMs) {
+    const found = await nativeLocate(ctx.client, ctx.ops.selectors, target, timeoutMs, ctx.render);
+    if (!found)
+        throw new NotFound(`${ctx.ops.describe(target)} was not found within ${Math.round(timeoutMs / 100) / 10} s`);
+    ctx.onLocated?.(found);
+    return found;
+}
+async function visibleCount(ctx, target) {
+    const ids = await nativeFindAll(ctx.client, ctx.ops.selectors, { ...target, fallbacks: undefined }, ctx.render);
+    const pool = target.nth === undefined ? ids : ids.slice(target.nth, target.nth + 1);
+    let count = 0;
+    for (const id of pool) {
+        if (await ctx.client.isElementDisplayed(id).catch(() => false))
+            count += 1;
+    }
+    return count;
+}
+/** Retries a command while the element is still settling (stale, not yet interactable). */
+async function retrying(ctx, target, timeoutMs, command) {
+    const deadline = Date.now() + timeoutMs;
+    let found = await element(ctx, target, timeoutMs);
+    for (;;) {
+        try {
+            await command(found.elementId);
+            return;
+        }
+        catch (error) {
+            const message = webdriverMessage(error);
+            if (Date.now() >= deadline || !/stale element|not interactable|no longer attached|not hittable|element not/i.test(message))
+                throw error;
+            await sleep(200);
+            found = await element(ctx, target, Math.max(100, deadline - Date.now()));
+        }
+    }
+}
+/** Performs one native desktop DSL action other than launch/terminate/focus_window. */
+export async function runNativeAction(ctx, action) {
+    const timeout = action.timeout_ms ?? ctx.defaultTimeoutMs;
+    const { client, ops } = ctx;
+    switch (action.type) {
+        case 'click':
+            await retrying(ctx, requireTarget(action), timeout, (id) => ops.click(id));
+            return {};
+        case 'double_click':
+            await retrying(ctx, requireTarget(action), timeout, (id) => ops.doubleClick(id));
+            return {};
+        case 'right_click':
+            await retrying(ctx, requireTarget(action), timeout, (id) => ops.rightClick(id));
+            return {};
+        case 'hover':
+            await retrying(ctx, requireTarget(action), timeout, (id) => ops.hover(id));
+            return {};
+        case 'type': {
+            const value = ctx.render(action.value ?? '');
+            await retrying(ctx, requireTarget(action), timeout, async (id) => {
+                if (action.clear)
+                    await client.elementClear(id);
+                if (value)
+                    await client.elementSendKeys(id, value);
+            });
+            return {};
+        }
+        case 'clear':
+            await retrying(ctx, requireTarget(action), timeout, (id) => client.elementClear(id));
+            return {};
+        case 'press': {
+            const chord = parseDesktopKey(action.key ?? '');
+            const found = action.target ? await element(ctx, action.target, timeout) : null;
+            await ops.press(chord, found?.elementId ?? null);
+            return {};
+        }
+        case 'check':
+        case 'uncheck': {
+            const wanted = action.type === 'check';
+            const target = requireTarget(action);
+            const found = await element(ctx, target, timeout);
+            const current = await ops.isChecked(found.elementId);
+            if (current === null)
+                throw new Error(`${ops.describe(target)} is not a checkbox, switch or radio button`);
+            if (current !== wanted)
+                await ops.click(found.elementId);
+            await expectWithin(Math.min(timeout, 3_000), async () => (await ops.isChecked(found.elementId)) === wanted, `${ops.describe(target)} to be ${wanted ? 'checked' : 'unchecked'}`);
+            return {};
+        }
+        case 'select_option': {
+            const found = await element(ctx, requireTarget(action), timeout);
+            await ops.selectOption(found.elementId, ctx.render(action.value ?? ''), timeout);
+            return {};
+        }
+        case 'wait':
+            await sleep(Math.min(Math.max(action.ms ?? 0, 0), 30_000));
+            return {};
+        case 'screenshot':
+            return { screenshot: Buffer.from(await client.takeScreenshot(), 'base64') };
+        case 'wait_for':
+        case 'expect_visible': {
+            const target = requireTarget(action);
+            await expectWithin(timeout, async () => {
+                const found = await nativeLocate(client, ops.selectors, target, 0, ctx.render);
+                if (!found)
+                    return false;
+                const shown = await client.isElementDisplayed(found.elementId).catch(() => false);
+                if (shown)
+                    ctx.onLocated?.(found);
+                return shown;
+            }, `${ops.describe(target)} to be visible`);
+            return {};
+        }
+        case 'expect_hidden': {
+            const target = requireTarget(action);
+            await expectWithin(timeout, async () => (await visibleCount(ctx, target)) === 0, `${ops.describe(target)} to be hidden`);
+            return {};
+        }
+        case 'expect_text': {
+            const target = requireTarget(action);
+            const expected = ctx.render(action.value ?? '');
+            let actual = '';
+            await expectWithin(timeout, async () => {
+                const found = await nativeLocate(client, ops.selectors, target, 0, ctx.render);
+                if (!found) {
+                    actual = '(not found)';
+                    return false;
+                }
+                actual = await ops.text(found.elementId);
+                return matches(actual, expected, action.match);
+            }, () => `text of ${ops.describe(target)} to ${verb(action.match)} "${expected}", found "${clip(actual)}"`);
+            return {};
+        }
+        case 'tap':
+            throw new Unsupported(`'tap' is not a ${ops.platform} action; use click`);
+        case 'fill':
+            throw new Unsupported(`'fill' is not a ${ops.platform} action; use type`);
+        case 'goto':
+        case 'deep_link':
+            throw new Unsupported(`'${action.type}' is not a ${ops.platform} action; start the app with launch`);
+        default:
+            throw new Unsupported(`'${action.type}' is not a ${ops.platform} action`);
+    }
+}

package/dist/src/drivers/webdriver/native-locate.js

@@ -0,0 +1,273 @@
+import { setTimeout as sleep } from 'node:timers/promises';
+import { Unsupported } from '../driver.js';
+import { predicateString } from './ios-locate.js';
+import { candidates, elementIdOf } from './locate.js';
+const NON_LOCATOR_KEYS = ['exact', 'nth', 'fallbacks', 'locate'];
+const MAX_EXPRESSION_CHARS = 500;
+function namedKeys(target) {
+    return Object.keys(target).filter((key) => !NON_LOCATOR_KEYS.includes(key));
+}
+function checkLength(kind, value) {
+    if (value.length > MAX_EXPRESSION_CHARS)
+        throw new Unsupported(`${kind} must be at most ${MAX_EXPRESSION_CHARS} characters`);
+    return value;
+}
+// ---------------------------------------------------------------------------------------------
+// macOS (Appium Mac2 / WebDriverAgentMac)
+// ---------------------------------------------------------------------------------------------
+/** macOS locator keys (plan §3, contracts §M): no `xpath` on macOS. */
+export const MACOS_LOCATORS = ['identifier', 'title', 'role', 'predicate', 'class_chain'];
+/** Accessibility roles → XCUIElementType names (what Mac2 queries and its page source use). */
+export const MAC_TYPE_BY_ROLE = {
+    AXApplication: 'Application',
+    AXWindow: 'Window',
+    AXSheet: 'Sheet',
+    AXDrawer: 'Drawer',
+    AXDialog: 'Dialog',
+    AXButton: 'Button',
+    AXRadioButton: 'RadioButton',
+    AXRadioGroup: 'RadioGroup',
+    AXCheckBox: 'CheckBox',
+    AXDisclosureTriangle: 'DisclosureTriangle',
+    AXPopUpButton: 'PopUpButton',
+    AXComboBox: 'ComboBox',
+    AXMenuButton: 'MenuButton',
+    AXPopover: 'Popover',
+    AXToolbar: 'Toolbar',
+    AXTabGroup: 'TabGroup',
+    AXTable: 'Table',
+    AXRow: 'TableRow',
+    AXColumn: 'TableColumn',
+    AXOutline: 'Outline',
+    AXBrowser: 'Browser',
+    AXList: 'CollectionView',
+    AXSlider: 'Slider',
+    AXProgressIndicator: 'ProgressIndicator',
+    AXBusyIndicator: 'ActivityIndicator',
+    AXLink: 'Link',
+    AXImage: 'Image',
+    AXSearchField: 'SearchField',
+    AXScrollArea: 'ScrollView',
+    AXScrollBar: 'ScrollBar',
+    AXStaticText: 'StaticText',
+    AXTextField: 'TextField',
+    AXSecureTextField: 'SecureTextField',
+    AXDateField: 'DatePicker',
+    AXTextArea: 'TextView',
+    AXMenu: 'Menu',
+    AXMenuItem: 'MenuItem',
+    AXMenuBar: 'MenuBar',
+    AXMenuBarItem: 'MenuBarItem',
+    AXWebArea: 'WebView',
+    AXIncrementor: 'Stepper',
+    AXSplitGroup: 'SplitGroup',
+    AXSplitter: 'Splitter',
+    AXColorWell: 'ColorWell',
+    AXHelpTag: 'HelpTag',
+    AXGrid: 'Grid',
+    AXLevelIndicator: 'LevelIndicator',
+    AXCell: 'Cell',
+    AXLayoutArea: 'LayoutArea',
+    AXLayoutItem: 'LayoutItem',
+    AXHandle: 'Handle',
+    AXRuler: 'Ruler',
+    AXRulerMarker: 'RulerMarker',
+    AXGroup: 'Group',
+    AXSegmentedControl: 'SegmentedControl',
+    AXSwitch: 'Switch',
+    AXToggle: 'Toggle',
+    AXValueIndicator: 'ValueIndicator',
+    AXDockItem: 'DockItem',
+    AXMatte: 'Matte',
+    AXUnknown: 'Other',
+};
+/** XCUIElementType name (without prefix) → accessibility role; the first role wins for shared types. */
+export const MAC_ROLE_BY_TYPE = Object.fromEntries(Object.entries(MAC_TYPE_BY_ROLE)
+    .reverse()
+    .map(([role, type]) => [type, role]));
+/** `AXButton` → `XCUIElementTypeButton`; throws for roles WebDriverAgentMac has no element type for. */
+export function macElementType(role) {
+    const trimmed = role.trim();
+    if (!/^AX[A-Za-z]+$/.test(trimmed))
+        throw new Unsupported(`role '${role}' is not an accessibility role (for example AXButton)`);
+    const type = MAC_TYPE_BY_ROLE[trimmed];
+    if (!type)
+        throw new Unsupported(`role '${trimmed}' has no macOS element type the runner can query; use predicate or class_chain`);
+    return `XCUIElementType${type}`;
+}
+/**
+ * Maps one macos target (without fallbacks/nth) to Mac2 selectors:
+ * - `identifier`: the accessibility identifier (`accessibility id`).
+ * - `title`: title or label, exact unless `exact: false` (then contains).
+ * - `role`: an AX role, queried by element type.
+ * - `predicate`, `class_chain`: used as they are.
+ * There is no `xpath` locator on macOS (the server refuses it too).
+ */
+export function macSelectors(target, render = (t) => t) {
+    if (target.identifier !== undefined)
+        return [{ using: 'accessibility id', value: render(target.identifier) }];
+    if (target.title !== undefined) {
+        const title = predicateString(render(target.title));
+        const op = target.exact === false ? 'CONTAINS' : '==';
+        return [{ using: '-ios predicate string', value: `title ${op} ${title} OR label ${op} ${title}` }];
+    }
+    if (target.role !== undefined)
+        return [{ using: 'class name', value: macElementType(render(target.role)) }];
+    if (target.predicate !== undefined)
+        return [{ using: '-ios predicate string', value: checkLength('predicate', render(target.predicate).trim()) }];
+    if (target.class_chain !== undefined)
+        return [{ using: '-ios class chain', value: checkLength('class_chain', render(target.class_chain).trim()) }];
+    const named = namedKeys(target);
+    throw new Unsupported(named.length > 0 ? `'${named[0]}' is not a macos locator; use one of ${MACOS_LOCATORS.join(', ')}` : 'the target names no locator');
+}
+export function describeMacTarget(target) {
+    if (target.identifier !== undefined)
+        return `identifier "${target.identifier}"`;
+    if (target.title !== undefined)
+        return `element titled "${target.title}"`;
+    if (target.role !== undefined)
+        return target.nth !== undefined ? `${target.role} #${target.nth + 1}` : target.role;
+    if (target.predicate !== undefined)
+        return `predicate ${target.predicate}`;
+    if (target.class_chain !== undefined)
+        return `class chain ${target.class_chain}`;
+    return 'element';
+}
+// ---------------------------------------------------------------------------------------------
+// Windows (Appium Windows driver / WinAppDriver, UI Automation)
+// ---------------------------------------------------------------------------------------------
+export const WINDOWS_LOCATORS = ['automation_id', 'name', 'class_name', 'control_type', 'xpath'];
+/** UI Automation control types a `control_type` locator may name (contracts §M). */
+export const WINDOWS_CONTROL_TYPES = [
+    'Button',
+    'Edit',
+    'Text',
+    'CheckBox',
+    'ComboBox',
+    'List',
+    'ListItem',
+    'MenuItem',
+    'Tab',
+    'TabItem',
+    'Tree',
+    'TreeItem',
+    'Window',
+    'Pane',
+    'Document',
+    'Hyperlink',
+    'Image',
+    'RadioButton',
+    'Slider',
+    'Spinner',
+    'ToolBar',
+    'DataGrid',
+    'DataItem',
+    'Custom',
+];
+/** Quotes a string for an XPath 1.0 literal (no escapes exist: split around quotes with concat). */
+export function xpathLiteral(value) {
+    if (!value.includes('"'))
+        return `"${value}"`;
+    if (!value.includes("'"))
+        return `'${value}'`;
+    return `concat(${value
+        .split('"')
+        .map((part) => `"${part}"`)
+        .join(`, '"', `)})`;
+}
+/**
+ * Maps one windows target (without fallbacks/nth) to WinAppDriver selectors:
+ * - `automation_id`: the UIA AutomationId (`accessibility id`).
+ * - `name`: the UIA Name, exact unless `exact: false` (then an xpath `contains`).
+ * - `class_name`: the UIA ClassName.
+ * - `control_type`: the control type as the page source's tag (`//Button`), locale independent.
+ * - `xpath`: used as is.
+ */
+export function windowsSelectors(target, render = (t) => t) {
+    if (target.automation_id !== undefined)
+        return [{ using: 'accessibility id', value: render(target.automation_id) }];
+    if (target.name !== undefined) {
+        const name = render(target.name);
+        if (target.exact === false)
+            return [{ using: 'xpath', value: `//*[contains(@Name, ${xpathLiteral(name)})]` }];
+        return [{ using: 'name', value: name }];
+    }
+    if (target.class_name !== undefined)
+        return [{ using: 'class name', value: render(target.class_name) }];
+    if (target.control_type !== undefined) {
+        const type = render(target.control_type).trim();
+        if (!WINDOWS_CONTROL_TYPES.includes(type)) {
+            throw new Unsupported(`control_type '${type}' is not a UI Automation control type; use one of ${WINDOWS_CONTROL_TYPES.join(', ')}`);
+        }
+        return [{ using: 'xpath', value: `//${type}` }];
+    }
+    if (target.xpath !== undefined)
+        return [{ using: 'xpath', value: checkLength('xpath', render(target.xpath)) }];
+    const named = namedKeys(target);
+    throw new Unsupported(named.length > 0 ? `'${named[0]}' is not a windows locator; use one of ${WINDOWS_LOCATORS.join(', ')}` : 'the target names no locator');
+}
+export function describeWindowsTarget(target) {
+    if (target.automation_id !== undefined)
+        return `automation id "${target.automation_id}"`;
+    if (target.name !== undefined)
+        return `element named "${target.name}"`;
+    if (target.class_name !== undefined)
+        return `class ${target.class_name}`;
+    if (target.control_type !== undefined)
+        return target.nth !== undefined ? `${target.control_type} #${target.nth + 1}` : target.control_type;
+    if (target.xpath !== undefined)
+        return `xpath ${target.xpath}`;
+    return 'element';
+}
+// ---------------------------------------------------------------------------------------------
+// Shared lookup
+// ---------------------------------------------------------------------------------------------
+/**
+ * A ref from a snapshot carries where the element was (runner-private `locate`): try the
+ * suggestion first, then that position (Windows `xpath`, macOS `class_chain`).
+ */
+export function resolveNativeRef(target) {
+    const { locate, ...rest } = target;
+    const position = typeof locate?.class_chain === 'string' ? { class_chain: locate.class_chain } : typeof locate?.xpath === 'string' ? { xpath: locate.xpath } : null;
+    if (!position)
+        return rest;
+    return { ...rest, fallbacks: [...(rest.fallbacks ?? []), position] };
+}
+/** Elements matching one target (no fallbacks), in document order. */
+export async function nativeFindAll(client, selectors, target, render) {
+    for (const selector of selectors(target, render)) {
+        const found = await client.findElements(selector.using, selector.value).catch((error) => {
+            const message = error instanceof Error ? error.message : String(error);
+            // A malformed predicate, class chain or xpath is the script's problem, not a missing element.
+            if (/invalid selector|InvalidSelector|Unable to parse|parse the format|is not a valid|Invalid class chain|Invalid locator/i.test(message) && !/no such element/i.test(message)) {
+                throw error;
+            }
+            return [];
+        });
+        if (found.length > 0)
+            return found.map(elementIdOf);
+    }
+    return [];
+}
+/** One pass over the target and its fallbacks; null when nothing matches (at `nth`). */
+export async function nativeLocateOnce(client, selectors, target, render) {
+    for (const candidate of candidates(target)) {
+        const ids = await nativeFindAll(client, selectors, candidate, render);
+        const nth = candidate.nth ?? 0;
+        if (ids.length > nth)
+            return { elementId: ids[nth], target: candidate, count: ids.length };
+    }
+    return null;
+}
+/** Polls until the target (or a fallback) matches or `timeoutMs` passes. */
+export async function nativeLocate(client, selectors, target, timeoutMs, render, pollMs = 300) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        const found = await nativeLocateOnce(client, selectors, target, render);
+        if (found)
+            return found;
+        if (Date.now() >= deadline)
+            return null;
+        await sleep(pollMs);
+    }
+}