elementus-ai 1.0.0 → 1.0.2

package/README.md

@@ -7,7 +7,7 @@ When a selector breaks, Elementus uses AI to find the element by natural-languag
 ## Installation
 
 ```bash
-npm install elementus
+npm install elementus-ai
 ```
 
 ## One-Prompt Setup
@@ -18,7 +18,7 @@ Copy this prompt to your AI coding agent (Claude, Cursor, Copilot, etc.) and it
 <summary><strong>Click to copy the setup prompt</strong></summary>
 
 ```
-I just installed the npm package "elementus" — a self-healing element resolution library for test automation. Analyze my project and integrate it. Follow these steps:
+I just installed the npm package "elementus-ai" — a self-healing element resolution library for test automation. Analyze my project and integrate it. Follow these steps:
 
 1. DETECT MY FRAMEWORK
    - Search for: playwright.config, wdio.conf, appium config files
@@ -39,7 +39,9 @@ I just installed the npm package "elementus" — a self-healing element resoluti
    - Set actionTimeout: 10000 in playwright config (Elementus respects framework timeouts)
 
    For WebDriverIO:
-   - Add el.wrapBrowser(browser) in the before hook in wdio.conf.js
+   - In wdio.conf.js before hook, wrap browser and override global $:
+     const wrapped = el.wrapBrowser(browser); globalThis.$ = wrapped.$.bind(wrapped)
+   - This way all page objects use plain $() with optional { ai } — zero changes needed
 
    For Appium:
    - Add el.wrapBrowser(driver) in the before hook
@@ -73,7 +75,7 @@ Rules:
 ## Quick Start
 
 ```javascript
-const { createElementus } = require('elementus')
+const { createElementus } = require('elementus-ai')
 
 const el = createElementus({
   provider: 'gemini',
@@ -133,7 +135,7 @@ await p.locator('#email', { ai: 'Email input field' }).fill('test@test.com')
 ```javascript
 // fixtures.js
 const { test: base } = require('@playwright/test')
-const { createElementus } = require('elementus')
+const { createElementus } = require('elementus-ai')
 const el = createElementus({ provider: 'gemini', geminiApiKey: '...' })
 
 module.exports = base.extend({
@@ -150,10 +152,25 @@ test('example', async ({ page }) => {
 
 ### WebDriverIO
 
+Override the global `$` in your `wdio.conf.js` so all page objects work transparently:
+
 ```javascript
-const b = el.wrapBrowser(browser)
-await b.$('#btn', { ai: 'Submit order button' }).click()
-await b.$('#email', { ai: 'Email input field' }).setValue('test@test.com')
+// wdio.conf.js
+const { createElementus } = require('elementus-ai')
+const el = createElementus({ provider: 'gemini', geminiApiKey: '...' })
+
+exports.config = {
+  // ... other config
+  async before() {
+    const wrapped = el.wrapBrowser(browser)
+    globalThis.$ = wrapped.$.bind(wrapped)
+  }
+}
+
+// In tests / page objects — plain $() with optional { ai }:
+await $('[data-testid="btn-send"]')                                // unchanged, zero overhead
+await $('#btn', { ai: 'Submit order button' }).click()              // self-healing
+await $('#email', { ai: 'Email input field' }).setValue('test@test.com')
 ```
 
 ### Appium (Native Android / iOS / Flutter)

package/elementus.js

@@ -328,7 +328,11 @@ function createElementus(userConfig = {}) {
       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)
+      const fnStr = fn.toString()
+      if (args !== undefined) {
+        return ctx.execute(`(${fnStr})(${JSON.stringify(args)})`)
+      }
+      return ctx.execute(`(${fnStr})()`)
     }
     throw new Error('Context must have evaluate() (Playwright) or execute() (WDIO)')
   }
@@ -375,7 +379,8 @@ function createElementus(userConfig = {}) {
     // 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'
+      typeof ctx.evaluate !== 'function' &&
+      typeof ctx.execute !== 'function'
   }
 
   // ── LLM helpers — multi-provider ─────────────────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "elementus-ai",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Self-healing element resolution for Playwright, WDIO & Appium. AI-powered fallback when selectors break.",
   "main": "elementus.js",
   "keywords": [
@@ -36,6 +36,7 @@
   },
   "files": [
     "elementus.js",
+    "wdio.d.ts",
     "README.md",
     "LICENSE"
   ]

package/wdio.d.ts

@@ -0,0 +1,7 @@
+/// <reference types="webdriverio" />
+
+declare global {
+  function $(selector: string, options?: { ai?: string }): WebdriverIO.Element
+}
+
+export {}