elementus-ai 1.0.0

package/elementus.js

@@ -0,0 +1,1288 @@
+/**
+ * ╔════════════════════════════════════════════════════════════════════╗
+ * ║  Elementus — Self-healing element resolution for Playwright & WDIO  ║
+ * ╚══════════════════════════════���═════════════════════════════════════╝
+ *
+ * When a selector breaks, elementus uses AI to find the element by
+ * natural-language description. Works with any action (click, fill, hover)
+ * and any assertion (toHaveText, toBeVisible). Supports local LLMs via
+ * LM Studio and cloud LLMs via Google Gemini API.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * 1. INSTALLATION
+ * ─────────────────────────────────────────────────────────────────────────
+ *
+ *   npm install elementus
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * 2. LLM PROVIDER SETUP (choose one)
+ * ─────────────────────────────────────────────────────────────────────────
+ *
+ * Option A — Local LLM via LM Studio (free, private, no API key):
+ *   1. Download LM Studio from https://lmstudio.ai
+ *   2. Load a vision-capable model (e.g., gemma-4-26b-a4b-it)
+ *   3. Start the local server (default: http://localhost:1234)
+ *   4. Configure:
+ *        const el = createElementus({
+ *          provider: 'lmstudio',
+ *          lmStudioUrl: 'http://localhost:1234/v1/chat/completions',
+ *          model: 'gemma-4-26b-a4b-it',
+ *        })
+ *
+ * Option B — Google Gemini API (cloud, fast, better vision):
+ *   1. Get an API key from https://aistudio.google.com/apikey
+ *   2. Configure:
+ *        const el = createElementus({
+ *          provider: 'gemini',
+ *          geminiApiKey: 'AIza...',     // or set GEMINI_API_KEY env var
+ *          geminiModel: 'gemini-2.5-flash',
+ *        })
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * 3. FRAMEWORK SETUP
+ * ─────────────────────────────────────────────────────────────────────────
+ *
+ * Playwright — wrap page once, add { ai } to any locator:
+ *
+ *   const { createElementus } = require('elementus')
+ *   const el = createElementus({ provider: 'gemini', geminiApiKey: '...' })
+ *
+ *   // In test or fixture:
+ *   const p = el.wrapPage(page)
+ *   await p.locator('#btn', { ai: 'Submit order button' }).click()
+ *   await p.locator('#email', { ai: 'Email input field' }).fill('test@test.com')
+ *
+ *   // Locators WITHOUT { ai } work normally — zero overhead:
+ *   await p.locator('#always-stable').click()
+ *
+ * Playwright fixture (recommended — wrap once for all tests):
+ *
+ *   // fixtures.js
+ *   const { test: base } = require('@playwright/test')
+ *   const { createElementus } = require('elementus')
+ *   const el = createElementus({ provider: 'gemini', geminiApiKey: '...' })
+ *
+ *   module.exports = base.extend({
+ *     page: async ({ page }, use) => {
+ *       await use(el.wrapPage(page))
+ *     }
+ *   })
+ *
+ *   // In tests — page is already wrapped:
+ *   test('example', async ({ page }) => {
+ *     await page.locator('#btn', { ai: 'Submit button' }).click()
+ *   })
+ *
+ * WDIO — wrap browser once, add { ai } to any $() selector:
+ *
+ *   const { createElementus } = require('elementus')
+ *   const el = createElementus({ provider: 'lmstudio' })
+ *
+ *   // In before hook or config:
+ *   const b = el.wrapBrowser(browser)
+ *   await b.$('#btn', { ai: 'Submit order button' }).click()
+ *   await b.$('#email', { ai: 'Email input field' }).setValue('test@test.com')
+ *
+ *   // $() calls WITHOUT { ai } work normally:
+ *   await b.$('#always-stable').click()
+ *
+ * Appium (native Android/iOS/Flutter) — same wrapBrowser pattern:
+ *
+ *   const { createElementus } = require('elementus')
+ *   const el = createElementus({ provider: 'gemini', geminiApiKey: '...' })
+ *
+ *   // In before hook:
+ *   const d = el.wrapBrowser(driver)
+ *   await d.$('~loginButton', { ai: 'Login button on welcome screen' }).click()
+ *   await d.$('~emailField', { ai: 'Email input' }).setValue('test@test.com')
+ *
+ *   // Works with Flutter, React Native, native Android/iOS — any Appium driver.
+ *   // Instead of DOM scanning, Elementus parses the native element tree
+ *   // from driver.getPageSource() (XML) and applies the same AI scoring.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * 4. API REFERENCE
+ * ─────────────────────────────────────────────────────────────────────────
+ *
+ * el.wrapPage(page)
+ *   Wraps a Playwright page. Returns a proxy where page.locator(selector,
+ *   { ai: 'description' }) auto-creates AI-fallback locators.
+ *   Locators without { ai } pass through unchanged.
+ *
+ * el.wrapBrowser(browser)
+ *   Wraps a WDIO browser. Returns a proxy where browser.$(selector,
+ *   { ai: 'description' }) auto-creates AI-fallback elements.
+ *   $() calls without { ai } pass through unchanged.
+ *
+ * el.wrap(context, locator, description)
+ *   Low-level: wraps any single locator/element with AI fallback.
+ *   Use wrapPage/wrapBrowser instead for cleaner code.
+ *   - context: page (Playwright) or browser (WDIO)
+ *   - locator: Playwright Locator or WDIO Element
+ *   - description: natural-language element description
+ *   Returns a Proxy that tries the original, falls back to AI on failure.
+ *
+ * el.find(context, description)
+ *   Find element by description only (no locator needed).
+ *   Returns a real Playwright Locator / WDIO Element for any action.
+ *   - context: page (Playwright) or browser (WDIO)
+ *   - description: natural-language element description
+ *   Example:
+ *     const el = await el.find(page, 'Submit button')
+ *     await el.click()
+ *     await expect(el).toHaveText('Submit')
+ *
+ * el.locate(context, locator, description)
+ *   Try locator first, fall back to AI if locator fails.
+ *   Returns a Playwright Locator / WDIO Element.
+ *   Respects your framework's configured action timeout.
+ *   Example:
+ *     const el = await el.locate(page, page.locator('#btn'), 'Submit')
+ *     await el.click()
+ *
+ * el.click(context, locator, description)
+ *   Click with optimized fallback: uses page.goto() for links (avoids
+ *   hover/overlay issues) and JS click for buttons (no mouse movement).
+ *   Use this for navigation clicks. For other actions, use wrap/find.
+ *   Respects your framework's configured action timeout.
+ *   Example:
+ *     await el.click(page, page.locator('#nav'), 'Blog page link')
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * 5. CONFIGURATION OPTIONS
+ * ─────────────────────────────────────────────────────────────────────────
+ *
+ * createElementus({
+ *   // LLM Provider
+ *   provider: 'lmstudio',    // 'lmstudio' | 'gemini'
+ *
+ *   // LM Studio (when provider = 'lmstudio')
+ *   lmStudioUrl: 'http://localhost:1234/v1/chat/completions',
+ *   model: 'gemma-4-26b-a4b-it',
+ *
+ *   // Gemini (when provider = 'gemini')
+ *   geminiApiKey: null,       // or GEMINI_API_KEY env var
+ *   geminiModel: 'gemini-2.5-flash',
+ *
+ *   // Behavior
+ *   maxCandidates: 20,        // max elements sent to LLM for disambiguation
+ *   visionMaxWidth: 1280,     // max screenshot width (px) sent to vision LLM
+ *
+ *   // Debugging
+ *   debug: false,             // save screenshots to debugDir
+ *   debugDir: './debug',      // directory for debug screenshots
+ *
+ *   // Custom stop words (merged with defaults)
+ *   stopWords: null,          // Set of words to ignore in descriptions
+ * })
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * 6. HOW IT WORKS (fallback pipeline)
+ * ─────────────────────────────────────────────────────────────────────────
+ *
+ * When a locator/selector fails, elementus runs this pipeline:
+ *
+ *   Step 1: Locator/Selector
+ *   Try the original selector. If it works, done — zero overhead.
+ *
+ *   Step 2: DOM Scoring
+ *   Scan all interactive elements on the page. Score each by keyword
+ *   and phrase relevance to the description. If one clear winner, use it.
+ *   If multiple tied: send top candidates to LLM for disambiguation.
+ *   If all identical (e.g., 10x "Edit" buttons): use positional LLM
+ *   with coordinates ("first Edit button near the top").
+ *
+ *   Step 3: Vision (last resort)
+ *   Take a full-page screenshot with a 3x3 labeled grid overlay.
+ *   Ask the vision LLM which region contains the target element.
+ *   Scroll to that region, re-scan DOM. If still unresolved,
+ *   ask LLM for precise pixel coordinates.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * 7. TIPS FOR WRITING DESCRIPTIONS
+ * ─────────────────────────────────────────────────────────────────────────
+ *
+ * Good descriptions use words that appear in or near the element:
+ *   'Submit order button'          — matches <button>Submit</button>
+ *   'Email input field'            — matches <input> near "Email" label
+ *   'Privacy Policy footer link'   — matches <a>Privacy Policy</a>
+ *
+ * For identical elements, add positional context:
+ *   'first Edit button near the top'
+ *   'Delete button in the third row'
+ *   'Add to Cart for the last product'
+ *
+ * Avoid vague descriptions:
+ *   BAD:  'the button'             — matches every button
+ *   BAD:  'click here'             — no useful keywords
+ *   GOOD: 'Save Changes button'    — specific, matchable text
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * 8. WHICH API TO USE FOR WHAT
+ * ─────────────────────────────────────────────────────────────────────────
+ *
+ * "I want to click a link/button":
+ *   → Use wrapPage + { ai } or el.click
+ *     await p.locator('#btn', { ai: 'Submit order' }).click()
+ *
+ * "I want to fill an input":
+ *   → Use wrapPage + { ai }
+ *     await p.locator('#email', { ai: 'Email input' }).fill('a@b.com')
+ *
+ * "I want to read text or an attribute":
+ *   → Use wrapPage + { ai } or el.find
+ *     const text = await p.locator('#price', { ai: 'Product price' }).textContent()
+ *     const href = await p.locator('#link', { ai: 'Blog link' }).getAttribute('href')
+ *
+ * "I want to assert (expect) on an element":
+ *   → Use el.find — returns a real locator you can pass to expect()
+ *     const el = await el.find(page, 'Submit order button')
+ *     await expect(el).toBeVisible()
+ *     await expect(el).toHaveText('Submit')
+ *     await expect(el).toHaveAttribute('href', '/checkout')
+ *
+ * "I want to check isVisible / isEnabled (boolean result)":
+ *   → Just use { ai } — handled automatically. Boolean query methods
+ *     (isVisible, isEnabled, isChecked, isHidden, isEditable) are detected
+ *     by the Proxy and resolve via AI first, then query the real element.
+ *     const vis = await p.locator('#gone', { ai: 'Submit' }).isVisible()  // true
+ *     const on  = await p.locator('#gone', { ai: 'Checkbox' }).isChecked() // true/false
+ *
+ * "I want to navigate to a page via link click":
+ *   → Use el.click — it uses page.goto(href) which is faster and avoids
+ *     CSS hover/overlay issues that regular click() can trigger.
+ *     await el.click(page, page.locator('#blog'), 'Blog page link')
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ */
+
+const fs = require('fs')
+const path = require('path')
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Defaults & constants
+// ─────────────────────────────────────────────────────────────────────────────
+
+const DEFAULTS = {
+  provider: 'lmstudio',
+  lmStudioUrl: 'http://localhost:1234/v1/chat/completions',
+  model: 'gemma-4-26b-a4b-it',
+  geminiApiKey: null,
+  geminiModel: 'gemini-2.5-flash',
+  maxCandidates: 20,
+  debug: false,
+  debugDir: null,
+  stopWords: null,
+  visionMaxWidth: 1280,
+}
+
+const DEFAULT_STOP_WORDS = new Set([
+  'the', 'a', 'an', 'and', 'or', 'but', 'in', 'on', 'at', 'to', 'for', 'of',
+  'with', 'by', 'from', 'is', 'it', 'its', 'this', 'that', 'be', 'are', 'was',
+  'were', 'has', 'have', 'had', 'do', 'does', 'did', 'will', 'would', 'not',
+  'link', 'button', 'click', 'press', 'navigate', 'navigation', 'nav',
+  'page', 'menu', 'top', 'bottom', 'footer', 'header', 'sidebar', 'bar',
+  'find', 'locate', 'element', 'item', 'icon', 'label', 'text', 'section'
+])
+
+const INTERACTIVE_TAGS = ['a', 'button', 'input', 'select', 'textarea', 'label', 'summary']
+const INTERACTIVE_ROLES = ['button', 'link', 'menuitem', 'menuitemcheckbox', 'menuitemradio',
+  'tab', 'checkbox', 'radio', 'option', 'combobox', 'switch', 'treeitem', 'gridcell']
+const INTERACTIVE_SELECTORS = 'a, button, input, select, textarea, [role="button"], [role="link"], [role="menuitem"], [role="tab"], [role="checkbox"], [role="radio"]'
+
+const REGION_LABELS = [
+  ['top-left',    'top-center',    'top-right'   ],
+  ['middle-left', 'middle-center', 'middle-right'],
+  ['bottom-left', 'bottom-center', 'bottom-right'],
+]
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Factory
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Create a elementus instance with the given configuration.
+ *
+ * @param {Object} userConfig
+ * @param {'lmstudio'|'gemini'} [userConfig.provider='lmstudio'] - LLM provider
+ * @param {string} [userConfig.lmStudioUrl='http://localhost:1234/v1/chat/completions'] - LM Studio endpoint
+ * @param {string} [userConfig.model='gemma-4-26b-a4b-it'] - LM Studio model name
+ * @param {string|null} [userConfig.geminiApiKey=null] - Google Gemini API key (or GEMINI_API_KEY env var)
+ * @param {string} [userConfig.geminiModel='gemini-2.5-flash'] - Gemini model ID
+ * @param {number} [userConfig.maxCandidates=20] - max elements sent to LLM for disambiguation
+ * @param {boolean} [userConfig.debug=false] - save debug screenshots
+ * @param {string|null} [userConfig.debugDir=null] - directory for debug screenshots
+ * @param {Set<string>|null} [userConfig.stopWords=null] - custom stop words (replaces defaults)
+ * @param {number} [userConfig.visionMaxWidth=1280] - max screenshot width (px) sent to vision LLM
+ * @returns {{ wrap, wrapPage, wrapBrowser, locate, find, click }}
+ */
+function createElementus(userConfig = {}) {
+  const config = { ...DEFAULTS, ...userConfig }
+  const stopWords = config.stopWords || DEFAULT_STOP_WORDS
+
+  // ── Driver adapter — auto-detects Playwright vs WDIO ─────────────────
+
+  function _eval(ctx, fn, args) {
+    // Playwright: page.evaluate(fn, args)  |  WDIO: browser.execute(fn, args)
+    if (typeof ctx.evaluate === 'function') {
+      return args !== undefined ? ctx.evaluate(fn, args) : ctx.evaluate(fn)
+    }
+    if (typeof ctx.execute === 'function') {
+      return args !== undefined ? ctx.execute(fn, args) : ctx.execute(fn)
+    }
+    throw new Error('Context must have evaluate() (Playwright) or execute() (WDIO)')
+  }
+
+  async function _screenshot(ctx, fullPage = false) {
+    if (typeof ctx.screenshot === 'function') {
+      // Playwright — returns Buffer
+      const buf = await ctx.screenshot({ type: 'png', fullPage, scale: 'css' })
+      return { buffer: buf, base64: buf.toString('base64') }
+    }
+    if (typeof ctx.takeScreenshot === 'function') {
+      // WDIO — returns base64 string (viewport only)
+      const b64 = await ctx.takeScreenshot()
+      return { buffer: Buffer.from(b64, 'base64'), base64: b64 }
+    }
+    throw new Error('Context must have screenshot() (Playwright) or takeScreenshot() (WDIO)')
+  }
+
+  async function _goto(ctx, url) {
+    if (typeof ctx.goto === 'function') return ctx.goto(url, { waitUntil: 'load' })
+    if (typeof ctx.url === 'function') return ctx.url(url)
+    // Native apps: no URL navigation — silently skip
+    if (_isNative(ctx)) return
+    throw new Error('Context must have goto() (Playwright) or url() (WDIO)')
+  }
+
+  async function _wait(ctx, ms) {
+    if (typeof ctx.waitForTimeout === 'function') return ctx.waitForTimeout(ms)
+    if (typeof ctx.pause === 'function') return ctx.pause(ms)
+  }
+
+  async function _makeLocator(ctx, selector) {
+    // Playwright: sync locator()  |  WDIO: async $()
+    if (typeof ctx.locator === 'function') return ctx.locator(selector)
+    if (typeof ctx.$ === 'function') return ctx.$(selector)
+    throw new Error('Context must have locator() (Playwright) or $() (WDIO)')
+  }
+
+  function _isPlaywright(ctx) {
+    return typeof ctx.evaluate === 'function'
+  }
+
+  function _isNative(ctx) {
+    // Appium native: has getPageSource but no evaluate/execute for browser JS
+    // (or execute exists but would fail — we detect via getPageSource presence + no DOM)
+    return typeof ctx.getPageSource === 'function' &&
+      typeof ctx.evaluate !== 'function'
+  }
+
+  // ── LLM helpers — multi-provider ─────────────────────────────────────
+
+  async function _lmStudioText(prompt, maxTokens) {
+    const res = await fetch(config.lmStudioUrl, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        model: config.model,
+        messages: [{ role: 'user', content: prompt }],
+        max_tokens: maxTokens, temperature: 0
+      })
+    })
+    if (!res.ok) throw new Error(`LM Studio ${res.status}: ${await res.text()}`)
+    return (await res.json()).choices[0].message.content.trim()
+  }
+
+  async function _lmStudioVision(prompt, base64Image, maxTokens) {
+    const res = await fetch(config.lmStudioUrl, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        model: config.model,
+        messages: [{ role: 'user', content: [
+          { type: 'text', text: prompt },
+          { type: 'image_url', image_url: { url: `data:image/png;base64,${base64Image}` } }
+        ]}],
+        max_tokens: maxTokens, temperature: 0
+      })
+    })
+    if (!res.ok) throw new Error(`LM Studio ${res.status}: ${await res.text()}`)
+    return (await res.json()).choices[0].message.content.trim()
+  }
+
+  function _geminiUrl() {
+    const key = config.geminiApiKey || process.env.GEMINI_API_KEY
+    if (!key) throw new Error('Gemini API key required: set geminiApiKey or GEMINI_API_KEY env var')
+    return `https://generativelanguage.googleapis.com/v1beta/models/${config.geminiModel}:generateContent?key=${key}`
+  }
+
+  function _geminiExtractText(data) {
+    if (!data.candidates?.[0]?.content?.parts) {
+      console.log(`[LLM] Gemini raw response: ${JSON.stringify(data).slice(0, 500)}`)
+      throw new Error('Unexpected Gemini response structure')
+    }
+    const parts = data.candidates[0].content.parts
+    // Thinking models return multiple parts (thought + output) — take the last text part
+    for (let i = parts.length - 1; i >= 0; i--) {
+      if (parts[i].text && !parts[i].thought) return parts[i].text.trim()
+    }
+    // Fallback: return any text part
+    for (let i = parts.length - 1; i >= 0; i--) {
+      if (parts[i].text) return parts[i].text.trim()
+    }
+    throw new Error('No text in Gemini response')
+  }
+
+  async function _geminiText(prompt, maxTokens) {
+    const res = await fetch(_geminiUrl(), {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        contents: [{ parts: [{ text: prompt }] }],
+        generationConfig: { maxOutputTokens: maxTokens, temperature: 0, responseMimeType: 'application/json', thinkingConfig: { thinkingBudget: 0 } }
+      })
+    })
+    if (!res.ok) throw new Error(`Gemini ${res.status}: ${await res.text()}`)
+    return _geminiExtractText(await res.json())
+  }
+
+  async function _geminiVision(prompt, base64Image, maxTokens) {
+    const res = await fetch(_geminiUrl(), {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        contents: [{ parts: [
+          { text: prompt },
+          { inline_data: { mime_type: 'image/png', data: base64Image } }
+        ]}],
+        generationConfig: { maxOutputTokens: maxTokens, temperature: 0, responseMimeType: 'application/json', thinkingConfig: { thinkingBudget: 0 } }
+      })
+    })
+    if (!res.ok) throw new Error(`Gemini ${res.status}: ${await res.text()}`)
+    return _geminiExtractText(await res.json())
+  }
+
+  async function askLLMText(prompt, maxTokens = 131072) {
+    const t0 = Date.now()
+    const result = config.provider === 'gemini' ? await _geminiText(prompt, maxTokens) : await _lmStudioText(prompt, maxTokens)
+    console.log(`[LLM] Text response: ${Date.now() - t0}ms`)
+    return result
+  }
+
+  async function askLLMVision(prompt, base64Image, maxTokens = 131072) {
+    const t0 = Date.now()
+    const result = config.provider === 'gemini' ? await _geminiVision(prompt, base64Image, maxTokens) : await _lmStudioVision(prompt, base64Image, maxTokens)
+    console.log(`[LLM] Vision response: ${Date.now() - t0}ms`)
+    return result
+  }
+
+  function parseJSON(content) {
+    const start = content.indexOf('{')
+    if (start === -1) throw new Error(`No JSON found in: ${content}`)
+    let depth = 0
+    for (let i = start; i < content.length; i++) {
+      if (content[i] === '{') depth++
+      else if (content[i] === '}') {
+        depth--
+        if (depth === 0) return JSON.parse(content.slice(start, i + 1))
+      }
+    }
+    throw new Error(`Unbalanced JSON in: ${content}`)
+  }
+
+  function saveDebug(filename, buffer) {
+    if (!config.debug || !config.debugDir) return
+    fs.mkdirSync(config.debugDir, { recursive: true })
+    fs.writeFileSync(path.join(config.debugDir, filename), buffer)
+  }
+
+  async function _resizeScreenshot(ctx, shot, origWidth, origHeight) {
+    const maxW = config.visionMaxWidth
+    if (origWidth <= maxW) return { base64: shot.base64, scale: 1 }
+    const scale = origWidth / maxW
+    const newH = Math.round(origHeight / scale)
+    const resized = await _eval(ctx, ({ b64, w, h }) => {
+      const img = new Image()
+      const canvas = document.createElement('canvas')
+      canvas.width = w; canvas.height = h
+      return new Promise(resolve => {
+        img.onload = () => {
+          canvas.getContext('2d').drawImage(img, 0, 0, w, h)
+          resolve(canvas.toDataURL('image/png').split(',')[1])
+        }
+        img.src = 'data:image/png;base64,' + b64
+      })
+    }, { b64: shot.base64, w: maxW, h: newH })
+    console.log(`[Vision] Resized screenshot: ${origWidth}×${origHeight} → ${maxW}×${newH} (scale ${scale.toFixed(2)}x)`)
+    return { base64: resized, scale }
+  }
+
+  // ── Native app XML parsing (Appium) ───────────────────────────────
+
+  // Interactive element types in Android/iOS/Flutter native trees
+  const NATIVE_INTERACTIVE = new Set([
+    // Android
+    'android.widget.button', 'android.widget.imagebutton', 'android.widget.edittext',
+    'android.widget.checkbox', 'android.widget.radiobutton', 'android.widget.switch',
+    'android.widget.togglebutton', 'android.widget.spinner', 'android.widget.imageview',
+    'android.widget.textview', 'android.view.view',
+    // iOS
+    'xcuielementtypebutton', 'xcuielementtypetextfield', 'xcuielementtypesecuretextfield',
+    'xcuielementtypeswitch', 'xcuielementtypepicker', 'xcuielementtypeimage',
+    'xcuielementtypestatictext', 'xcuielementtypeother', 'xcuielementtypecell',
+    'xcuielementtypelink',
+  ])
+
+  function _parseNativeXml(xmlSource) {
+    // Lightweight XML parser — extracts elements with bounds and text from
+    // Appium's getPageSource() XML. Works for Android and iOS element trees.
+    const elements = []
+    // Match self-closing and open tags with attributes
+    const tagRegex = /<([a-zA-Z0-9._]+)\s([^>]*?)\/?>|<([a-zA-Z0-9._]+)\s([^>]*?)>[^<]*<\/\3>/g
+    let match
+
+    while ((match = tagRegex.exec(xmlSource)) !== null) {
+      const tagName = (match[1] || match[3] || '').toLowerCase()
+      const attrs = match[2] || match[4] || ''
+
+      // Extract attributes (indexOf is faster than creating RegExp per call)
+      const get = (name) => {
+        const needle = name + '="'
+        const i = attrs.indexOf(needle)
+        if (i === -1) return null
+        const start = i + needle.length
+        return attrs.substring(start, attrs.indexOf('"', start))
+      }
+
+      // Get text from various attribute names across platforms
+      const text = (get('text') || get('content-desc') || get('label') ||
+        get('name') || get('value') || '').trim()
+      if (!text) continue
+
+      // Get bounds — Android: bounds="[x1,y1][x2,y2]", iOS: x,y,width,height attrs
+      let docX = 0, docY = 0
+      const bounds = get('bounds')
+      if (bounds) {
+        // Android format: [x1,y1][x2,y2]
+        const bm = bounds.match(/\[(\d+),(\d+)\]\[(\d+),(\d+)\]/)
+        if (bm) {
+          docX = Math.round((+bm[1] + +bm[3]) / 2)
+          docY = Math.round((+bm[2] + +bm[4]) / 2)
+        }
+      } else {
+        // iOS format: separate x, y, width, height attributes
+        const x = +(get('x') || 0), y = +(get('y') || 0)
+        const w = +(get('width') || 0), h = +(get('height') || 0)
+        if (w === 0 || h === 0) continue
+        docX = Math.round(x + w / 2)
+        docY = Math.round(y + h / 2)
+      }
+
+      if (docX <= 0 && docY <= 0) continue
+
+      // Determine if interactive (by type or clickable attribute)
+      const clickable = get('clickable') === 'true' || get('enabled') === 'true'
+      const isInteractive = NATIVE_INTERACTIVE.has(tagName) || clickable
+
+      if (!isInteractive) continue
+
+      elements.push({
+        text: text.replace(/\s+/g, ' '),
+        tag: tagName.split('.').pop(), // 'android.widget.Button' → 'button'
+        role: get('class') || tagName,
+        href: null, // native apps don't have hrefs
+        docX,
+        docY,
+        // Native-specific: store identifiers for locator building
+        _resourceId: get('resource-id') || null,
+        _accessibilityId: get('content-desc') || get('accessibility-id') || get('label') || null,
+        _xpath: null, // set later if needed
+      })
+    }
+
+    return elements
+  }
+
+  async function getAllElementsNative(ctx) {
+    const source = await ctx.getPageSource()
+    const elements = _parseNativeXml(source)
+    console.log(`[Native] Parsed ${elements.length} interactive elements from page source`)
+    return elements
+  }
+
+  // Build an Appium locator from native element data (no DOM attribute stamping)
+  async function markByElementNative(ctx, element) {
+    // Priority: accessibility-id > resource-id > xpath by text
+    if (element._accessibilityId) {
+      console.log(`[Resolve] Native: accessibility-id "${element._accessibilityId}"`)
+      return ctx.$(`~${element._accessibilityId}`)
+    }
+    if (element._resourceId) {
+      console.log(`[Resolve] Native: resource-id "${element._resourceId}"`)
+      return ctx.$(`android=new UiSelector().resourceId("${element._resourceId}")`)
+    }
+    // Fallback: find by text content
+    console.log(`[Resolve] Native: text "${element.text}"`)
+    const escapedText = element.text.replace(/"/g, '\\"')
+    // Try accessibility id first (works cross-platform), then text-based
+    const found = await ctx.$(`~${element.text}`).catch(() => null)
+    if (found && await found.isExisting()) return found
+    // Android UiSelector fallback
+    return ctx.$(`android=new UiSelector().text("${escapedText}")`)
+  }
+
+  // ── DOM scanning (web) ───────────────────────────────────────────────
+
+  async function getAllElements(ctx) {
+    // Dispatch: native app → parse XML, web → evaluate JS in browser
+    if (_isNative(ctx)) return getAllElementsNative(ctx)
+    return _eval(ctx, ({ selectors }) => {
+      function extract(el) {
+        const rect = el.getBoundingClientRect()
+        if (rect.width === 0 || rect.height === 0) return null
+        const docX = Math.round(rect.left + window.scrollX + rect.width / 2)
+        if (docX < 0 || docX > window.innerWidth) return null
+        const text = el.textContent.trim().replace(/\s+/g, ' ')
+        if (!text) return null
+        return {
+          text,
+          tag:  el.tagName.toLowerCase(),
+          role: el.getAttribute('role') || null,
+          href: el.getAttribute('href') || null,
+          docX,
+          docY: Math.round(rect.top + window.scrollY + rect.height / 2),
+        }
+      }
+      // Fast pass: interactive selectors + onclick + tabindex (no getComputedStyle)
+      const seen = new Set()
+      const results = []
+      for (const el of document.querySelectorAll(selectors + ',[onclick],[tabindex]')) {
+        if (seen.has(el)) continue
+        seen.add(el)
+        const data = extract(el)
+        if (data) results.push(data)
+      }
+      // Slow pass: cursor:pointer elements not caught by selectors
+      for (const el of document.querySelectorAll('*')) {
+        if (seen.has(el)) continue
+        if (window.getComputedStyle(el).cursor === 'pointer') {
+          const data = extract(el)
+          if (data) results.push(data)
+        }
+      }
+      return results
+    }, { selectors: INTERACTIVE_SELECTORS })
+  }
+
+  // ── Scoring ──────────────────────────────────────────────────────────
+
+  function _normalizeWords(description) {
+    return description.toLowerCase().replace(/[^a-z0-9& ]/g, ' ').split(/\s+/).filter(w => w.length > 1)
+  }
+
+  function extractKeywordsAndPhrases(description) {
+    const words = _normalizeWords(description)
+    const keywords = words.filter(w => !stopWords.has(w))
+    const phrases = []; let run = []
+    for (const w of words) {
+      if (!stopWords.has(w)) { run.push(w) }
+      else { if (run.length >= 2) phrases.push(run.join(' ')); run = [] }
+    }
+    if (run.length >= 2) phrases.push(run.join(' '))
+    return { keywords, phrases }
+  }
+
+  function scoreCandidate(el, keywords, phrases) {
+    return phrases.reduce((s, p) => s + (el._ltext.includes(p) || el._lhref.includes(p) ? 3 : 0), 0) +
+           keywords.reduce((s, kw) => s + (el._ltext.includes(kw) || el._lhref.includes(kw) ? 1 : 0), 0)
+  }
+
+  // ── Element resolution ───────────────────────────────────────────────
+
+  async function findElementInDOM(ctx, description, regionBounds = null) {
+    let elements = await getAllElements(ctx)
+
+    if (elements.length === 0) {
+      for (let attempt = 0; attempt < 3; attempt++) {
+        console.log(`[DOM] 0 elements \u2014 waiting for render (${attempt + 1}/3)`)
+        await _wait(ctx, 1000)
+        elements = await getAllElements(ctx)
+        if (elements.length > 0) break
+      }
+    }
+
+    const seen = new Set()
+    elements = elements.filter(e => {
+      const key = `${e.text}|${e.docX}|${e.docY}`
+      return seen.has(key) ? false : seen.add(key)
+    })
+
+    if (regionBounds) {
+      const { x1, y1, x2, y2 } = regionBounds
+      elements = elements.filter(e => e.docX >= x1 && e.docX <= x2 && e.docY >= y1 && e.docY <= y2)
+      console.log(`[DOM] ${elements.length} elements in region`)
+    } else {
+      console.log(`[DOM] ${elements.length} elements on page`)
+    }
+
+    if (elements.length === 0) return null
+
+    // Pre-compute lowercase text/href for scoring (avoids repeated toLowerCase per element)
+    elements.forEach(e => { e._ltext = e.text.toLowerCase(); e._lhref = (e.href || '').toLowerCase() })
+
+    const { keywords, phrases } = extractKeywordsAndPhrases(description)
+    console.log(`[DOM] Keywords: [${keywords.join(', ')}] | Phrases: [${phrases.join(', ')}]`)
+
+    const scored = elements
+      .map(e => ({ ...e, score: scoreCandidate(e, keywords, phrases) }))
+      .filter(e => e.score > 0)
+      .sort((a, b) => b.score - a.score)
+
+    if (scored.length === 0) {
+      if (!regionBounds) { console.log(`[DOM] No matches \u2014 signalling vision`); return null }
+      const capped = elements.slice(0, config.maxCandidates)
+      console.log(`[DOM] No matches in region \u2014 sending ${capped.length} to LLM`)
+      return disambiguateWithLLM(capped, description)
+    }
+
+    const topScore   = scored[0].score
+    const topMatches = scored.filter(e => e.score === topScore)
+    console.log(`[DOM] Top score: ${topScore} | Top matches: ${topMatches.length}`)
+    topMatches.slice(0, 5).forEach(e => console.log(`  [${e.score}] <${e.role || e.tag}> "${e.text}"`))
+
+    if (topMatches.length === 1) {
+      console.log(`[DOM] Clear match: "${topMatches[0].text}"`)
+      return topMatches[0]
+    }
+
+    if (!regionBounds && topMatches.length / elements.length > 0.4) {
+      console.log(`[DOM] Keyword too generic \u2014 signalling vision`); return null
+    }
+
+    const firstHref = topMatches[0].href || ''
+    const shortestLen = Math.min(...topMatches.map(e => e.text.length))
+    const firstPrefix = topMatches[0].text.slice(0, shortestLen).toLowerCase()
+    const allIdentical = topMatches.every(e =>
+      e.text.slice(0, shortestLen).toLowerCase() === firstPrefix && (e.href || '') === firstHref
+    )
+    if (allIdentical) {
+      console.log(`[DOM] ${topMatches.length} identical ("${firstPrefix}") \u2014 positional LLM`)
+      return disambiguateWithPosition(topMatches, description)
+    }
+
+    const capped = topMatches.slice(0, config.maxCandidates)
+    console.log(`[DOM] ${capped.length} tied \u2014 LLM disambiguating...`)
+    return disambiguateWithLLM(capped, description)
+  }
+
+  async function disambiguateWithLLM(candidates, description) {
+    const list = candidates.map((e, i) => {
+      const hint = e.href ? ` \u2192 ${e.href}` : ''
+      return `[${i}] <${e.role || e.tag}> "${e.text}"${hint}`
+    }).join('\n')
+    let content
+    try {
+      content = await askLLMText(
+        `I need to click: "${description}"\n\nCandidates:\n${list}\n\nReturn ONLY JSON: {"index": <number>}`)
+    } catch (err) { console.log(`[DOM] LLM failed: ${err.message}`); return null }
+    console.log(`[DOM] LLM response: ${content}`)
+    let parsed = null
+    try { const { index } = parseJSON(content); if (typeof index === 'number' && isFinite(index)) parsed = Math.round(index) } catch {}
+    if (parsed === null || parsed < 0 || parsed >= candidates.length) {
+      console.log(`[DOM] Invalid index (${parsed}) \u2014 signalling vision`); return null
+    }
+    const chosen = candidates[parsed]
+    console.log(`[DOM] Chose [${parsed}]: "${chosen.text}" at doc(${chosen.docX}, ${chosen.docY})`)
+    return chosen
+  }
+
+  async function disambiguateWithPosition(candidates, description) {
+    const capped = candidates.slice(0, config.maxCandidates)
+    const list = capped.map((e, i) =>
+      `[${i}] <${e.role || e.tag}> "${e.text}" at position (x=${e.docX}, y=${e.docY})`
+    ).join('\n')
+    let content
+    try {
+      content = await askLLMText(
+        `I need to click: "${description}"\n\n` +
+        `Identical elements at different positions. Smaller y = higher on page.\n\n` +
+        `${list}\n\nReturn ONLY JSON: {"index": <number>}`)
+    } catch (err) { console.log(`[DOM] Positional LLM failed: ${err.message}`); return null }
+    console.log(`[DOM] Positional LLM: ${content}`)
+    let parsed = null
+    try { const { index } = parseJSON(content); if (typeof index === 'number' && isFinite(index)) parsed = Math.round(index) } catch {}
+    if (parsed === null || parsed < 0 || parsed >= capped.length) return null
+    const chosen = capped[parsed]
+    console.log(`[DOM] Positional: chose [${parsed}] at doc(${chosen.docX}, ${chosen.docY})`)
+    return chosen
+  }
+
+  // ── Vision ───────────────────────────────────────────────────────────
+
+  async function identifyRegionViaVision(ctx, description) {
+    // Combined eval: get dimensions + draw grid overlay in one round trip
+    const { viewWidth, docHeight } = await _eval(ctx, ({ labels }) => {
+      const w = window.innerWidth, h = document.body.scrollHeight
+      const canvas = document.createElement('canvas')
+      canvas.id = '__vision_grid__'
+      canvas.style.cssText = 'position:absolute;top:0;left:0;z-index:999999;pointer-events:none;'
+      canvas.width = w; canvas.height = h
+      document.body.appendChild(canvas)
+      const ctx = canvas.getContext('2d'), cw = w / 3, ch = h / 3
+      const fontSize = Math.max(16, Math.min(cw, ch) * 0.08)
+      for (let r = 0; r < 3; r++) for (let c = 0; c < 3; c++) {
+        const x = c * cw, y = r * ch
+        ctx.strokeStyle = 'rgba(255,50,50,0.7)'; ctx.lineWidth = 2
+        ctx.strokeRect(x + 1, y + 1, cw - 2, ch - 2)
+        ctx.font = `bold ${fontSize}px sans-serif`; ctx.textAlign = 'center'; ctx.textBaseline = 'middle'
+        const tw = ctx.measureText(labels[r][c]).width
+        ctx.fillStyle = 'rgba(0,0,0,0.6)'
+        ctx.fillRect(x + cw/2 - tw/2 - 4, y + ch/2 - fontSize/2 - 3, tw + 8, fontSize + 6)
+        ctx.fillStyle = 'white'; ctx.fillText(labels[r][c], x + cw / 2, y + ch / 2)
+      }
+      return { viewWidth: w, docHeight: h }
+    }, { labels: REGION_LABELS })
+
+    const shot = await _screenshot(ctx, true)
+    saveDebug('debug_region.png', shot.buffer)
+    await _eval(ctx, () => document.getElementById('__vision_grid__')?.remove())
+
+    const regionImg = await _resizeScreenshot(ctx, shot, viewWidth, docHeight)
+    const content = await askLLMVision(
+      `The screenshot shows a full webpage with a 3x3 grid:\n` +
+      `${REGION_LABELS.map(r => r.join(' | ')).join('\n')}\n\n` +
+      `Which region contains: "${description}"?\n` +
+      `Return ONLY JSON: {"region": "<label>"}\nValid: ${REGION_LABELS.flat().join(', ')}`,
+      regionImg.base64)
+    console.log(`[Vision] Region: ${content}`)
+
+    const { region: raw } = parseJSON(content)
+    const region = raw.toLowerCase().trim()
+    const row = REGION_LABELS.findIndex(r => r.includes(region))
+    const col = row >= 0 ? REGION_LABELS[row].indexOf(region) : -1
+    if (row < 0 || col < 0) throw new Error(`Unknown region: "${raw}"`)
+
+    const cw = viewWidth / 3, ch = docHeight / 3, OV = 0.20
+    return {
+      x1: Math.max(0, col * cw - cw * OV), y1: Math.max(0, row * ch - ch * OV),
+      x2: Math.min(viewWidth, (col + 1) * cw + cw * OV), y2: Math.min(docHeight, (row + 1) * ch + ch * OV),
+    }
+  }
+
+  async function locatePreciseViaVision(ctx, description) {
+    const { viewWidth, docHeight } = await _eval(ctx, () => ({
+      viewWidth: window.innerWidth, docHeight: document.body.scrollHeight
+    }))
+    const shot = await _screenshot(ctx, true)
+    saveDebug('debug_precise.png', shot.buffer)
+
+    const { base64: resizedB64, scale } = await _resizeScreenshot(ctx, shot, viewWidth, docHeight)
+    const resizedW = Math.round(viewWidth / scale), resizedH = Math.round(docHeight / scale)
+    const content = await askLLMVision(
+      `Screenshot: ${resizedW}\u00d7${resizedH}px (full page). Origin (0,0) = top-left.\n\n` +
+      `Find the CENTER of: "${description}"\n\n` +
+      `Return ONLY JSON: {"x": <number>, "y": <number>}`, resizedB64, 30)
+    console.log(`[Vision] Coordinates: ${content}`)
+
+    const { x, y } = parseJSON(content)
+    return {
+      docX: Math.max(0, Math.min(viewWidth - 1, Math.round(x * scale))),
+      docY: Math.max(0, Math.min(docHeight - 1, Math.round(y * scale)))
+    }
+  }
+
+  // ── Scroll, mark, click helpers ──────────────────────────────────────
+
+  async function scrollIntoView(ctx, docY) {
+    if (_isNative(ctx)) return // native apps handle scrolling differently — skip
+    const { scrollY, viewHeight } = await _eval(ctx, () => ({
+      scrollY: window.scrollY, viewHeight: window.innerHeight
+    }))
+    if (docY < scrollY || docY > scrollY + viewHeight) {
+      await _eval(ctx, top => window.scrollTo({ top, behavior: 'instant' }), docY - viewHeight / 2)
+    }
+  }
+
+  async function markByElement(ctx, element) {
+    if (_isNative(ctx)) return markByElementNative(ctx, element)
+    await scrollIntoView(ctx, element.docY)
+    const uid = `sr-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+    const marked = await _eval(ctx, ({ tag, text, href, docX, docY, uid }) => {
+      function isClippedByParent(el) {
+        const rect = el.getBoundingClientRect()
+        let p = el.parentElement
+        while (p && p !== document.body) {
+          const ps = window.getComputedStyle(p)
+          if (ps.overflow === 'hidden' || ps.overflow === 'clip' || ps.overflowY === 'hidden') {
+            const pr = p.getBoundingClientRect()
+            if (rect.bottom > pr.bottom + 1 || rect.top < pr.top - 1) return true
+          }
+          p = p.parentElement
+        }
+        return false
+      }
+      const candidates = []
+      const selector = href ? tag + '[href="' + CSS.escape(href) + '"]' : tag
+      for (const el of document.querySelectorAll(selector)) {
+        const elText = el.textContent.trim().replace(/\s+/g, ' ')
+        if (elText !== text) continue
+        const rect = el.getBoundingClientRect()
+        if (rect.width === 0 || rect.height === 0) continue
+        const cx = Math.round(rect.left + window.scrollX + rect.width / 2)
+        const cy = Math.round(rect.top + window.scrollY + rect.height / 2)
+        const dist = Math.abs(cx - docX) + Math.abs(cy - docY)
+        const visible = !isClippedByParent(el)
+        candidates.push({ el, dist, visible })
+      }
+      candidates.sort((a, b) => {
+        if (a.visible !== b.visible) return a.visible ? -1 : 1
+        return a.dist - b.dist
+      })
+      if (candidates.length === 0) return null
+      candidates[0].el.setAttribute('data-elementus', uid)
+      return candidates[0].el.tagName.toLowerCase()
+    }, { tag: element.tag, text: element.text, href: element.href, docX: element.docX, docY: element.docY, uid })
+
+    if (!marked) throw new Error(`Could not mark <${element.tag}> "${element.text}"`)
+    console.log(`[Resolve] Marked <${marked}> "${element.text}" at doc(${element.docX}, ${element.docY})`)
+    return _makeLocator(ctx, `[data-elementus="${uid}"]`)
+  }
+
+  async function markAtCoordinates(ctx, docX, docY) {
+    if (!_isNative(ctx)) await scrollIntoView(ctx, docY)
+    const uid = `sr-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+    const marked = await _eval(ctx, ({ docX, docY, uid, selectors }) => {
+      const vx = docX - window.scrollX, vy = docY - window.scrollY
+      const top = document.elementFromPoint(vx, vy)
+      if (!top) return null
+      let target = top.closest(selectors)
+      if (!target && typeof document.elementsFromPoint === 'function') {
+        for (const el of document.elementsFromPoint(vx, vy)) {
+          target = el.matches(selectors) ? el : el.closest(selectors)
+          if (target) break
+        }
+      }
+      const final = target || top
+      final.setAttribute('data-elementus', uid)
+      return final.tagName.toLowerCase()
+    }, { docX, docY, uid, selectors: INTERACTIVE_SELECTORS })
+    if (!marked) throw new Error(`No element at doc(${docX}, ${docY})`)
+    console.log(`[Resolve] Marked <${marked}> at doc(${docX}, ${docY})`)
+    return _makeLocator(ctx, `[data-elementus="${uid}"]`)
+  }
+
+  async function scrollAndClick(ctx, element) {
+    if (_isNative(ctx)) {
+      // Native app: resolve via markByElementNative, then click the element
+      console.log(`\u2713 Tapping "${element.text}" \u2014 native (${element.docX}, ${element.docY})`)
+      const nativeEl = await markByElementNative(ctx, element)
+      await nativeEl.click()
+      return
+    }
+    await scrollIntoView(ctx, element.docY)
+    const { vx, vy } = await _eval(ctx, ({ docX, docY }) => ({
+      vx: docX - window.scrollX, vy: docY - window.scrollY
+    }), { docX: element.docX, docY: element.docY })
+    console.log(`\u2713 Clicking "${element.text}" \u2014 doc(${element.docX}, ${element.docY})`)
+    if (element.href && element.tag === 'a') {
+      await _goto(ctx, element.href)
+      console.log(`[Click] Navigated to: ${element.href}`)
+      return
+    }
+    const clicked = await _eval(ctx, ({ x, y }) => {
+      const el = document.elementFromPoint(x, y)
+      if (!el) return 'null'
+      if (typeof el.click === 'function') el.click()
+      else el.dispatchEvent(new MouseEvent('click', { bubbles: true, cancelable: true }))
+      return el.tagName + ':' + (el.textContent?.trim().slice(0, 40) || '')
+    }, { x: vx, y: vy })
+    console.log(`[Click] JS click: ${clicked}`)
+  }
+
+  async function clickAtCoords(ctx, coords) {
+    if (_isNative(ctx)) {
+      // Native app: tap at absolute coordinates via Appium action
+      console.log(`[Vision] Native tap at (${coords.docX}, ${coords.docY})`)
+      await ctx.action('pointer', { parameters: { pointerType: 'touch' } })
+        .move({ x: coords.docX, y: coords.docY })
+        .down().up()
+        .perform()
+      return
+    }
+    await scrollIntoView(ctx, coords.docY)
+    const { vx, vy } = await _eval(ctx, ({ docX, docY }) => ({
+      vx: docX - window.scrollX, vy: docY - window.scrollY
+    }), { docX: coords.docX, docY: coords.docY })
+    const info = await _eval(ctx, ({ x, y }) => {
+      const el = document.elementFromPoint(x, y)
+      if (!el) return null
+      const a = el.closest('a')
+      return { href: a?.getAttribute('href') || null, isAnchor: !!a }
+    }, { x: vx, y: vy })
+    if (info?.href && info.isAnchor) {
+      await _goto(ctx, info.href)
+      console.log(`[Vision] Navigated to: ${info.href}`)
+      return
+    }
+    await _eval(ctx, ({ x, y }) => {
+      const el = document.elementFromPoint(x, y)
+      if (!el) return
+      if (typeof el.click === 'function') el.click()
+      else el.dispatchEvent(new MouseEvent('click', { bubbles: true, cancelable: true }))
+    }, { x: vx, y: vy })
+    console.log(`[Vision] JS click at (${vx}, ${vy})`)
+  }
+
+  // ── Vision fallback (shared) ─────────────────────────────────────────
+
+  async function visionFallback(ctx, description) {
+    console.log(`[Vision] DOM returned null \u2014 activating vision`)
+    const region = await identifyRegionViaVision(ctx, description)
+    const vh = await _eval(ctx, () => window.innerHeight)
+    await _eval(ctx, top => window.scrollTo({ top, behavior: 'instant' }), (region.y1 + region.y2) / 2 - vh / 2)
+    const element = await findElementInDOM(ctx, description, region)
+    if (element) return { element, coords: null }
+    console.log(`[Vision] DOM unresolved \u2014 precise coordinates...`)
+    const coords = await locatePreciseViaVision(ctx, description)
+    return { element: null, coords }
+  }
+
+  // ── Public API ───────────────────────────────────────────────────────
+
+  async function _findByDescription(ctx, description) {
+    let element = await findElementInDOM(ctx, description)
+    if (element) return markByElement(ctx, element)
+    try {
+      const result = await visionFallback(ctx, description)
+      if (result.element) return markByElement(ctx, result.element)
+      return markAtCoordinates(ctx, result.coords.docX, result.coords.docY)
+    } catch (err) {
+      throw new Error(`All fallback paths exhausted for "${description}": ${err.message}`)
+    }
+  }
+
+  /**
+   * Try locator first, fall back to AI-based description search if locator fails.
+   * Returns a framework-native locator/element usable for any action or assertion.
+   *
+   * @param {Object} ctx - page (Playwright) or browser (WDIO)
+   * @param {Object} locator - Playwright Locator or WDIO Element to try first
+   * @param {string} description - natural-language element description for AI fallback
+   * @returns {Promise<Object>} Playwright Locator or WDIO Element
+   */
+  async function locate(ctx, locator, description) {
+    try {
+      if (_isPlaywright(ctx)) {
+        await locator.waitFor({ state: 'attached' })
+      } else {
+        await locator.waitForExist()
+      }
+      console.log(`\u2713 Located via locator`)
+      return locator
+    } catch {
+      console.log(`\u2717 Locator failed \u2014 searching for: "${description}"`)
+    }
+    return _findByDescription(ctx, description)
+  }
+
+  /**
+   * Find an element by natural-language description only (no locator needed).
+   * Searches the page DOM, uses LLM disambiguation, and vision as last resort.
+   * Returns a framework-native locator/element usable for any action or assertion.
+   *
+   * @param {Object} ctx - page (Playwright) or browser (WDIO)
+   * @param {string} description - natural-language element description
+   * @returns {Promise<Object>} Playwright Locator or WDIO Element
+   *
+   * @example
+   *   const el = await el.find(page, 'Submit order button')
+   *   await el.click()
+   *   await expect(el).toHaveText('Submit')
+   */
+  async function find(ctx, description) {
+    console.log(`[Find] "${description}"`)
+    return _findByDescription(ctx, description)
+  }
+
+  /**
+   * Click with locator-first fallback + optimized click strategy.
+   * Uses page.goto() for <a href> links (avoids hover/overlay issues)
+   * and JS elementFromPoint click for buttons (no mouse cursor movement).
+   * Best for navigation actions. For fill/hover/assert, use wrap or find.
+   *
+   * @param {Object} ctx - page (Playwright) or browser (WDIO)
+   * @param {Object} locator - Playwright Locator or WDIO Element to try first
+   * @param {string} description - natural-language element description for AI fallback
+   * @returns {Promise<void>}
+   *
+   * @example
+   *   await el.click(page, page.locator('#nav-blog'), 'Blog page link')
+   */
+  async function click(ctx, locator, description) {
+    try {
+      await locator.click()
+      console.log(`\u2713 Clicked via locator`)
+      return
+    } catch {
+      console.log(`\u2717 Locator failed \u2014 searching for: "${description}"`)
+    }
+    let element = await findElementInDOM(ctx, description)
+    if (element) { await scrollAndClick(ctx, element); return }
+    try {
+      const result = await visionFallback(ctx, description)
+      if (result.element) { await scrollAndClick(ctx, result.element); return }
+      await clickAtCoords(ctx, result.coords)
+    } catch (err) {
+      throw new Error(`All fallback paths exhausted for "${description}": ${err.message}`)
+    }
+  }
+
+  /**
+   * Wrap a single locator/element with AI fallback. Returns a Proxy that
+   * intercepts all method calls (click, fill, textContent, getAttribute, etc.).
+   * If the original method fails, AI resolves the element and retries.
+   * The wrapped object looks and acts like the original — Playwright assertions,
+   * WDIO expect, and all framework APIs work transparently.
+   *
+   * For cleaner code, prefer wrapPage() or wrapBrowser() over calling this directly.
+   *
+   * @param {Object} driverContext - page (Playwright) or browser (WDIO)
+   * @param {Object} locator - Playwright Locator or WDIO Element
+   * @param {string} description - natural-language element description
+   * @returns {Proxy} Proxy that behaves like the original locator/element
+   *
+   * @example
+   *   const btn = el.wrap(page, page.locator('#old-btn'), 'Submit button')
+   *   await btn.click()          // tries #old-btn → fail → AI finds Submit → click
+   *   await btn.textContent()    // same fallback for any method
+   */
+  function wrap(driverContext, locator, description) {
+    const PASSTHROUGH = new Set([
+      'then', 'catch', 'finally', 'toString', 'valueOf', 'toJSON',
+      Symbol.toPrimitive, Symbol.toStringTag, Symbol.iterator, Symbol.asyncIterator,
+    ])
+    let _resolved = null
+
+    return new Proxy(locator, {
+      get(target, prop, receiver) {
+        if (typeof prop === 'symbol' || PASSTHROUGH.has(prop)) {
+          return Reflect.get(target, prop, receiver)
+        }
+        const original = target[prop]
+        if (typeof original !== 'function') return original
+
+        // Boolean query methods (isVisible, isEnabled, etc.) return false instead
+        // of throwing on missing elements. We can't detect failure from the return
+        // value, so resolve via AI first, then query the real element.
+        const BOOL_QUERIES = ['isVisible', 'isEnabled', 'isChecked', 'isHidden', 'isEditable']
+
+        return async function (...args) {
+          if (BOOL_QUERIES.includes(prop)) {
+            if (!_resolved) {
+              console.log(`[AI] ${prop}() \u2014 resolving via AI first for "${description}"`)
+              _resolved = await _findByDescription(driverContext, description)
+            }
+            return _resolved[prop](...args)
+          }
+
+          try {
+            return await original.apply(target, args)
+          } catch (firstError) {
+            console.log(`[AI] ${String(prop)}() failed \u2014 AI fallback for "${description}"`)
+            if (!_resolved) _resolved = await _findByDescription(driverContext, description)
+
+            const resolvedMethod = _resolved[prop]
+            if (typeof resolvedMethod !== 'function') {
+              if (prop in _resolved) return _resolved[prop]
+              throw firstError
+            }
+
+            if (prop === 'click' || prop === 'dblclick') {
+              const href = await _resolved.getAttribute('href').catch(() => null)
+              if (href) {
+                await _goto(driverContext, href)
+                console.log(`[AI] Navigated to: ${href}`)
+                return
+              }
+              return resolvedMethod.call(_resolved, { ...(args[0] || {}), force: true })
+            }
+            const FORCE_VAL = { fill: 1, type: 1, selectOption: 1, press: 1 }
+            let retryArgs = [...args]
+            if (['hover', 'tap', 'check', 'uncheck'].includes(prop)) {
+              retryArgs[0] = { ...(retryArgs[0] || {}), force: true }
+            } else if (prop in FORCE_VAL) {
+              retryArgs[FORCE_VAL[prop]] = { ...(retryArgs[FORCE_VAL[prop]] || {}), force: true }
+            }
+            return resolvedMethod.apply(_resolved, retryArgs)
+          }
+        }
+      }
+    })
+  }
+
+  /**
+   * Wrap a Playwright page so that page.locator(selector, { ai: 'description' })
+   * automatically creates AI-fallback locators. Locators without { ai } are
+   * returned unchanged — zero overhead on stable selectors.
+   *
+   * Call once per test (or in a fixture for all tests).
+   *
+   * @param {Object} pageObj - Playwright Page object
+   * @returns {Proxy} Proxied page with enhanced locator() method
+   *
+   * @example
+   *   const p = el.wrapPage(page)
+   *   await p.locator('#btn', { ai: 'Submit button' }).click()   // AI fallback
+   *   await p.locator('#btn').click()                              // normal, no AI
+   */
+  function wrapPage(pageObj) {
+    return new Proxy(pageObj, {
+      get(target, prop, receiver) {
+        if (prop === 'locator') {
+          return function (selector, options = {}) {
+            const { ai, ...locatorOptions } = options
+            const loc = Object.keys(locatorOptions).length > 0
+              ? target.locator(selector, locatorOptions) : target.locator(selector)
+            return ai ? wrap(target, loc, ai) : loc
+          }
+        }
+        return Reflect.get(target, prop, receiver)
+      }
+    })
+  }
+
+  /**
+   * Wrap a WDIO browser so that browser.$(selector, { ai: 'description' })
+   * automatically creates AI-fallback elements. $() calls without { ai }
+   * are returned unchanged — zero overhead on stable selectors.
+   *
+   * Call once in before() hook or wdio.conf.js.
+   *
+   * @param {Object} browserObj - WDIO Browser object
+   * @returns {Proxy} Proxied browser with enhanced $() method
+   *
+   * @example
+   *   const b = el.wrapBrowser(browser)
+   *   await b.$('#btn', { ai: 'Submit button' }).click()   // AI fallback
+   *   await b.$('#btn').click()                              // normal, no AI
+   */
+  function wrapBrowser(browserObj) {
+    return new Proxy(browserObj, {
+      get(target, prop, receiver) {
+        if (prop === '$') {
+          return function (selector, options = {}) {
+            const { ai, ...rest } = options
+            const el = Object.keys(rest).length > 0 ? target.$(selector, rest) : target.$(selector)
+            return ai ? wrap(target, el, ai) : el
+          }
+        }
+        return Reflect.get(target, prop, receiver)
+      }
+    })
+  }
+
+  return { wrap, wrapPage, wrapBrowser, locate, find, click }
+}
+
+module.exports = { createElementus }