playwright-genie 1.0.0 → 1.0.1

package/README.md

@@ -1,435 +1,492 @@
-# playwright-nlp-locator
+# playwright-genie
 
-> 🎯 Find Playwright locators using natural language descriptions powered by LLM
+> Find and interact with Playwright elements using natural language — powered by any LLM
 
-[![npm version](https://img.shields.io/npm/v/playwright-nlp-locator.svg)](https://www.npmjs.com/package/playwright-nlp-locator)
+[![npm version](https://img.shields.io/npm/v/playwright-genie.svg)](https://www.npmjs.com/package/playwright-genie)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-**playwright-nlp-locator** enables you to write browser automation scripts using plain English instead of manually inspecting elements and writing complex selectors. Simply describe the element you want to interact with, and the library will find the best Playwright locator for it.
+**playwright-genie** lets you write Playwright tests in plain English. No more hunting for selectors — just describe the element and the genie finds it.
 
-## ✨ Features
+## Features
 
-- 🗣️ **Natural Language Descriptions** - Describe elements in plain English
-- 🎯 **Smart Locator Generation** - Returns optimal locators (role-based > text-based > CSS)
-- 📊 **Confidence Scores** - Know how confident the match is
-- 🔄 **Alternative Suggestions** - Get multiple locator options
-- 🛠️ **TypeScript Support** - Full type definitions included
-- 🤖 **LLM-Powered** - Uses Abacus.AI APIs for intelligent matching
-- 📦 **Production Ready** - Error handling, edge cases, and best practices
+- **Natural Language** — describe elements in plain English, no selectors needed
+- **40+ Playwright Actions** — click, fill, check, hover, drag, wait, screenshot and more
+- **Any LLM Provider** — OpenAI, Claude, Ollama, Azure, or any OpenAI-compatible API
+- **Smart Caching** — persistent disk cache + in-memory cache to minimize LLM calls
+- **Action-Aware** — `fill('username')` targets the input, not the label
+- **Auto-Retry** — stale cached locators are automatically re-resolved
+- **TypeScript Support** — full type definitions included
+- **Single Page Object** — one `createSmartLocator(page)` works across all navigations
 
-## 📦 Installation
+## Installation
 
 ```bash
-npm install playwright-nlp-locator playwright
+npm install playwright-genie
 ```
 
 ### Prerequisites
 
-1. **Playwright** - The library works with Playwright
-2. **Python 3** - Required for LLM API calls
-3. **Abacus.AI Python SDK** - Install with `pip install abacusai`
-4. **Abacus.AI API Key** - Set the `ABACUS_API_KEY` environment variable
+- **Node.js** >= 18
+- **Playwright** >= 1.40
+- An **LLM API key** (OpenAI, Anthropic, or any OpenAI-compatible provider)
 
-```bash
-pip install abacusai
-export ABACUS_API_KEY="your-api-key-here"
+## Setup
+
+Create a `.env` file in your project root:
+
+```env
+# Option 1: OpenAI
+LLM_API_KEY=sk-your-openai-key
+LLM_MODEL=gpt-4o-mini
+
+# Option 2: Anthropic (via OpenAI-compatible proxy)
+LLM_API_KEY=your-anthropic-key
+LLM_BASE_URL=https://your-proxy.com/v1
+LLM_MODEL=claude-sonnet-4-20250514
+
+# Option 3: Ollama (local, free)
+LLM_API_KEY=ollama
+LLM_BASE_URL=http://localhost:11434/v1
+LLM_MODEL=llama3
+
+# Option 4: Azure OpenAI
+LLM_API_KEY=your-azure-key
+LLM_BASE_URL=https://your-resource.openai.azure.com/openai/deployments/your-deployment
+LLM_MODEL=gpt-4o-mini
+```
+
+Also supports `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, or `ROUTELLM_API_KEY` as fallbacks.
+
+## Quick Start
+
+### With Playwright Test
+
+```js
+import { test } from '@playwright/test';
+import { createSmartLocator } from 'playwright-genie';
+
+test('login flow', async ({ page }) => {
+  const smart = createSmartLocator(page);
+
+  await page.goto('https://myapp.com/login');
+  await smart.fill('username', 'admin');
+  await smart.fill('password', 'secret123');
+  await smart.click('login button');
+  await smart.waitForVisible('welcome heading');
+});
+```
+
+### Standalone Script
+
+```js
+import { chromium } from 'playwright';
+import { createSmartLocator } from 'playwright-genie';
+
+const browser = await chromium.launch();
+const page = await browser.newPage();
+const smart = createSmartLocator(page);
+
+await page.goto('https://myapp.com');
+await smart.click('sign in link');
+await smart.fill('email field', 'user@example.com');
+await smart.fill('password field', 'secret');
+await smart.click('submit button');
+
+await browser.close();
 ```
 
-## 🚀 Quick Start
+## API Reference
+
+### `createSmartLocator(page, options?)`
+
+Creates a smart locator instance bound to a Playwright page. Works across navigations — no need to recreate it.
+
+```js
+const smart = createSmartLocator(page, { verbose: true });
+```
+
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `verbose` | `boolean` | `false` | Log resolved locators to console |
+| `debug` | `boolean` | `false` | Enable detailed debug logging |
+| `model` | `string` | env var | Override LLM model |
+| `temperature` | `number` | `0` | LLM temperature |
+| `maxTokens` | `number` | `1024` | Max response tokens |
 
-```javascript
-const { chromium } = require('playwright');
-const { findLocator, createNLPHelper } = require('playwright-nlp-locator');
+---
 
-async function main() {
-  const browser = await chromium.launch();
-  const page = await browser.newPage();
-  await page.goto('https://example.com');
+### Interaction Actions
 
-  // Option 1: Get the locator string
-  const result = await findLocator(page, 'Login Button');
-  console.log(result.locator);  // e.g., "page.getByRole('button', { name: 'Login' })"
-  console.log(result.confidence);  // e.g., 0.95
+```js
+await smart.click('login button');
+await smart.click('submit', { force: true });
 
-  // Option 2: Use the NLP Helper for direct interaction
-  const nlp = createNLPHelper(page);
-  await nlp.click('Submit button');
-  await nlp.type('Email input field', 'user@example.com');
-  await nlp.type('Password field', 'secret123');
+await smart.dblclick('editable cell');
 
-  await browser.close();
-}
+await smart.fill('username', 'Admin');
+await smart.fill('email field', 'a@b.com', { timeout: 5000 });
 
-main();
+await smart.type('search box', 'hello');
+
+await smart.pressSequentially('otp input', '123456', { delay: 100 });
+
+await smart.press('search box', 'Enter');
+
+await smart.clear('email field');
+
+await smart.hover('profile menu');
+
+await smart.focus('first input');
+
+await smart.tap('mobile menu icon');
+
+await smart.select('country dropdown', 'India');
+
+await smart.selectText('paragraph content');
 ```
 
-## 📖 API Reference
+---
+
+### Checkbox & Radio
+
+```js
+await smart.check('remember me checkbox');
+
+await smart.uncheck('newsletter opt-in');
+
+await smart.setChecked('terms checkbox', true);
+```
 
-### `findLocator(page, description, options?)`
+---
 
-Find a Playwright locator using natural language description.
+### File Upload
 
-**Parameters:**
-- `page` - Playwright Page object
-- `description` - Natural language description of the element
-- `options` - Optional configuration object
+```js
+await smart.setInputFiles('file upload', '/path/to/file.pdf');
+await smart.setInputFiles('avatar input', ['/img1.png', '/img2.png']);
+```
 
-**Returns:** `Promise<FindLocatorResult>`
+---
 
-```javascript
-const result = await findLocator(page, 'email input field');
+### Drag & Drop
 
-// Result object:
-{
-  found: true,
-  locator: "page.getByPlaceholder('Enter your email')",
-  locatorType: 'placeholder',
-  confidence: 0.92,
-  explanation: 'Input field with placeholder text indicating email entry',
-  alternatives: [
-    { locator: "page.locator('#email')", confidence: 0.85 }
-  ],
-  elementIndex: 3
-}
+```js
+const { source, target } = await smart.dragTo('card item', 'drop zone');
 ```
 
-### `getLocator(page, description, options?)`
+---
+
+### Wait Actions
+
+```js
+await smart.waitForVisible('success toast');
+await smart.waitForVisible('modal', 10000);
+
+await smart.waitForHidden('loading spinner');
 
-Get an actual Playwright Locator object ready for interaction.
+await smart.waitForAttached('dynamic table');
 
-```javascript
-const { locator, result } = await getLocator(page, 'Submit button');
+await smart.waitForDetached('old modal');
 
-// Use the locator directly
-await locator.click();
-await locator.fill('text');
-const text = await locator.textContent();
+await smart.waitFor('element', { state: 'visible', timeout: 5000 });
 ```
 
-### `findAllLocators(page, description, options?)`
+---
+
+### State Queries
+
+```js
+const visible  = await smart.isVisible('error message');
+const hidden   = await smart.isHidden('loading spinner');
+const enabled  = await smart.isEnabled('submit button');
+const disabled = await smart.isDisabled('locked field');
+const checked  = await smart.isChecked('terms checkbox');
+const editable = await smart.isEditable('readonly field');
+const found    = await smart.exists('optional element');
+```
 
-Find multiple matching elements for a description.
+---
 
-```javascript
-const matches = await findAllLocators(page, 'navigation links');
+### Content Retrieval
 
-// Returns array of matches:
-[
-  { locator: "page.getByRole('link', { name: 'Home' })", confidence: 0.90, type: 'role' },
-  { locator: "page.getByRole('link', { name: 'About' })", confidence: 0.88, type: 'role' }
-]
+```js
+const text  = await smart.getText('welcome heading');
+const inner = await smart.getInnerText('article body');
+const html  = await smart.getInnerHTML('rich content area');
+const value = await smart.getInputValue('email field');
+const attr  = await smart.getAttribute('link', 'href');
+const box   = await smart.getBoundingBox('hero image');
+const num   = await smart.count('list items');
 ```
 
-### `createNLPHelper(page, options?)`
+---
 
-Create a helper object with natural language methods.
+### Scroll & Visual
 
-```javascript
-const nlp = createNLPHelper(page);
+```js
+await smart.scrollIntoView('footer section');
 
-// Available methods:
-await nlp.click('Login button');
-await nlp.type('Username field', 'john_doe');
-await nlp.select('Country dropdown', 'USA');
-await nlp.hover('Profile menu');
-await nlp.waitFor('Loading spinner to disappear');
-const text = await nlp.getText('Welcome message');
-const exists = await nlp.exists('Error message');
+const buffer = await smart.screenshot('chart area', { path: 'chart.png' });
+
+await smart.highlight('target element');
 ```
 
-## ⚙️ Configuration Options
-
-```javascript
-const options = {
-  // Maximum elements to analyze (default: 100)
-  maxElements: 100,
-  
-  // Include hidden elements (default: false)
-  includeHiddenElements: false,
-  
-  // Minimum confidence to accept (default: 0.5)
-  confidenceThreshold: 0.5,
-  
-  // LLM model to use (default: 'claude-3-5-sonnet')
-  model: 'claude-3-5-sonnet',
-  
-  // Locator preference order
-  preferredLocatorOrder: ['role', 'text', 'testId', 'css', 'xpath']
-};
-
-const result = await findLocator(page, 'Submit button', options);
+---
+
+### `smart.locate()` — Resolve Once, Act Many Times
+
+When you need multiple actions on the same element, use `locate()` to resolve the locator once:
+
+```js
+const el = await smart.locate('username');
+await el.clear();
+await el.fill('NewAdmin');
+await el.press('Tab');
+console.log(await el.inputValue());
+console.log(await el.isEnabled());
+
+// Access the raw Playwright locator
+const loc = el.rawLocator;
+
+// SmartAction has 40+ methods matching Playwright's Locator API
+await el.click();
+await el.hover();
+await el.screenshot({ path: 'element.png' });
+await el.waitForVisible();
+await el.evaluate((node) => node.style.border = '2px solid red');
 ```
 
-## 🎯 Best Practices for Descriptions
+---
 
-### ✅ Good Descriptions
+### `smart.prefetch()` — Batch Resolve
 
-```javascript
-// Be specific about the element type
-await nlp.click('Login button');
-await nlp.type('Email input field', 'user@example.com');
-await nlp.click('Submit form button');
+Pre-resolve multiple locators in a single LLM call to save time and cost:
 
-// Include context when needed
-await nlp.click('Add to cart button for the first product');
-await nlp.type('Search box in the header', 'shoes');
+```js
+await smart.prefetch('username', 'password', 'login button');
 
-// Use visual or functional descriptions
-await nlp.click('Red cancel button');
-await nlp.click('Hamburger menu icon');
-await nlp.click('Close modal X button');
+// These now hit the cache — no LLM calls
+await smart.fill('username', 'Admin');
+await smart.fill('password', 'secret');
+await smart.click('login button');
 ```
 
-### ❌ Avoid Vague Descriptions
+---
 
-```javascript
-// Too vague - could match multiple elements
-await nlp.click('button');
-await nlp.type('input', 'text');
+### Cache Management
 
-// Better alternatives:
-await nlp.click('primary submit button');
-await nlp.type('username input', 'text');
+```js
+smart.clearCache();       // clear in-memory cache only
+smart.clearAllCaches();   // clear both memory + disk (.locator-cache.json)
 ```
 
-## 📚 Complete Examples
+## Caching
 
-### Example 1: Login Form Automation
+**playwright-genie** uses a two-level cache to minimize LLM calls:
 
-```javascript
-const { chromium } = require('playwright');
-const { createNLPHelper } = require('playwright-nlp-locator');
+1. **Memory cache** — instant lookups within the same test run
+2. **Disk cache** (`.locator-cache.json`) — persists across runs
 
-async function loginAutomation() {
-  const browser = await chromium.launch();
-  const page = await browser.newPage();
-  
+Cache keys are scoped by **URL pathname + action + query**, so `fill('username')` on `/login` won't collide with `click('username')` on `/dashboard`.
+
+If a cached locator becomes stale (element no longer exists), it's automatically invalidated and re-resolved via LLM.
+
+Set `LOCATOR_CACHE_FILE` env var to customize the cache file path.
+
+## LLM Provider Configuration
+
+| Provider | `LLM_API_KEY` | `LLM_BASE_URL` | `LLM_MODEL` |
+|----------|---------------|-----------------|-------------|
+| OpenAI | `sk-...` | *(default)* | `gpt-4o-mini` |
+| Anthropic | `sk-ant-...` | proxy URL | `claude-sonnet-4-20250514` |
+| Ollama | `ollama` | `http://localhost:11434/v1` | `llama3` |
+| Azure OpenAI | Azure key | deployment URL | `gpt-4o-mini` |
+| RouteLLM | key | proxy URL | model name |
+
+## Complete Examples
+
+### Login Flow
+
+```js
+import { test, expect } from '@playwright/test';
+import { createSmartLocator } from 'playwright-genie';
+
+test('complete login flow', async ({ page }) => {
+  const smart = createSmartLocator(page);
   await page.goto('https://myapp.com/login');
-  
-  const nlp = createNLPHelper(page);
-  
-  // Fill login form using natural language
-  await nlp.type('Username or email input', 'john@example.com');
-  await nlp.type('Password field', 'secretPassword123');
-  
-  // Check "Remember me" if it exists
-  if (await nlp.exists('Remember me checkbox')) {
-    await nlp.click('Remember me checkbox');
+
+  await smart.fill('username', 'admin');
+  await smart.fill('password', 'secret123');
+
+  if (await smart.exists('remember me checkbox')) {
+    await smart.check('remember me checkbox');
   }
-  
-  // Submit the form
-  await nlp.click('Sign in button');
-  
-  // Wait for dashboard to load
-  await nlp.waitFor('Dashboard header');
-  
-  console.log('Login successful!');
-  
-  await browser.close();
-}
+
+  await smart.click('sign in button');
+  await smart.waitForVisible('dashboard heading');
+
+  const welcome = await smart.getText('welcome message');
+  expect(welcome).toContain('admin');
+});
 ```
 
-### Example 2: E-commerce Shopping Flow
+### E-commerce Flow
 
-```javascript
-async function shoppingFlow() {
-  const browser = await chromium.launch();
-  const page = await browser.newPage();
-  const nlp = createNLPHelper(page);
-  
+```js
+test('shopping flow', async ({ page }) => {
+  const smart = createSmartLocator(page);
   await page.goto('https://shop.example.com');
-  
-  // Search for a product
-  await nlp.type('Search bar', 'wireless headphones');
-  await nlp.click('Search button');
-  
-  // Filter results
-  await nlp.click('Price filter dropdown');
-  await nlp.click('Under $100 option');
-  
-  // Select a product
-  await nlp.click('First product in the list');
-  
-  // Add to cart
-  await nlp.select('Size selector', 'Medium');
-  await nlp.click('Add to cart button');
-  
-  // Proceed to checkout
-  await nlp.click('Shopping cart icon');
-  await nlp.click('Proceed to checkout button');
-  
-  // Fill shipping info
-  await nlp.type('First name field', 'John');
-  await nlp.type('Last name field', 'Doe');
-  await nlp.type('Address line 1', '123 Main St');
-  await nlp.type('City input', 'New York');
-  await nlp.select('State dropdown', 'NY');
-  await nlp.type('Zip code', '10001');
-  
-  await nlp.click('Continue to payment button');
-  
-  await browser.close();
-}
-```
 
-### Example 3: Form Validation Testing
+  await smart.fill('search bar', 'wireless headphones');
+  await smart.press('search bar', 'Enter');
+  await smart.waitForVisible('product list');
 
-```javascript
-const { findLocator, getLocator } = require('playwright-nlp-locator');
+  await smart.click('first product card');
+  await smart.select('size dropdown', 'Medium');
+  await smart.click('add to cart button');
 
-async function testFormValidation() {
-  const browser = await chromium.launch();
-  const page = await browser.newPage();
-  
-  await page.goto('https://myapp.com/signup');
-  
-  // Submit empty form to trigger validation
-  const { locator: submitBtn } = await getLocator(page, 'Submit button');
-  await submitBtn.click();
-  
-  // Check for validation errors
-  const emailError = await findLocator(page, 'Email validation error message');
-  if (emailError.found && emailError.confidence > 0.7) {
-    console.log('Email validation working:', emailError.locator);
-  }
-  
-  const passwordError = await findLocator(page, 'Password error message');
-  if (passwordError.found) {
-    const { locator } = await getLocator(page, 'Password error');
-    const errorText = await locator.textContent();
-    console.log('Password error:', errorText);
-  }
-  
-  await browser.close();
-}
+  await smart.waitForVisible('cart badge');
+  const count = await smart.getText('cart badge');
+  expect(count).toBe('1');
+});
 ```
 
-### Example 4: Dynamic Content Handling
+### Dynamic Content & Modals
 
-```javascript
-async function handleDynamicContent() {
-  const browser = await chromium.launch();
-  const page = await browser.newPage();
-  const nlp = createNLPHelper(page);
-  
+```js
+test('handle dynamic content', async ({ page }) => {
+  const smart = createSmartLocator(page);
   await page.goto('https://app.example.com');
-  
-  // Wait for dynamic content to load
-  await nlp.waitFor('Content loaded indicator');
-  
-  // Handle modals
-  if (await nlp.exists('Cookie consent popup')) {
-    await nlp.click('Accept cookies button');
-  }
-  
-  if (await nlp.exists('Newsletter subscription modal')) {
-    await nlp.click('Close modal button');
+
+  if (await smart.exists('cookie consent popup')) {
+    await smart.click('accept cookies button');
+    await smart.waitForHidden('cookie consent popup');
   }
-  
-  // Interact with lazy-loaded content
-  await page.evaluate(() => window.scrollTo(0, document.body.scrollHeight));
-  await nlp.waitFor('Load more button');
-  await nlp.click('Load more button');
-  
-  await browser.close();
-}
+
+  await smart.scrollIntoView('footer section');
+  await smart.waitForVisible('load more button');
+  await smart.click('load more button');
+  await smart.waitForHidden('loading spinner');
+});
 ```
 
-## 🔧 Locator Types
-
-The library returns different types of locators based on element attributes:
-
-| Type | Example | Priority |
-|------|---------|----------|
-| Role | `page.getByRole('button', { name: 'Submit' })` | 1 (Highest) |
-| Text | `page.getByText('Click here')` | 2 |
-| Label | `page.getByLabel('Email address')` | 3 |
-| Placeholder | `page.getByPlaceholder('Enter email')` | 4 |
-| TestId | `page.getByTestId('submit-btn')` | 5 |
-| CSS | `page.locator('button.primary')` | 6 |
-| XPath | `page.locator('//button[@id="submit"]')` | 7 (Lowest) |
-
-## 🐛 Error Handling
-
-```javascript
-const { findLocator, getLocator } = require('playwright-nlp-locator');
-
-// Method 1: Check result
-const result = await findLocator(page, 'Missing element');
-if (!result.found) {
-  console.log('Element not found:', result.error);
-}
-
-if (result.confidence < 0.5) {
-  console.log('Low confidence match - may be incorrect');
-}
-
-// Method 2: Try-catch with getLocator
-try {
-  const { locator } = await getLocator(page, 'Element description');
-  await locator.click();
-} catch (error) {
-  console.error('Failed to find element:', error.message);
-}
-
-// Method 3: Fallback locators
-const result = await findLocator(page, 'Submit button');
-if (result.confidence < 0.7 && result.alternatives?.length > 0) {
-  console.log('Using alternative locator:', result.alternatives[0].locator);
-}
+### Form Validation
+
+```js
+test('form validation', async ({ page }) => {
+  const smart = createSmartLocator(page);
+  await page.goto('https://myapp.com/signup');
+
+  await smart.click('submit button');
+  await smart.waitForVisible('email error message');
+
+  const error = await smart.getText('email error message');
+  expect(error).toContain('required');
+
+  await smart.fill('email field', 'user@example.com');
+  const enabled = await smart.isEnabled('submit button');
+  expect(enabled).toBe(true);
+});
 ```
 
-## 🔒 Security Notes
-
-- The library sends page DOM structure to the LLM API for analysis
-- Sensitive data in element values may be visible to the API
-- Consider using this in development/testing environments
-- For production, ensure compliance with your data policies
-
-## 📄 TypeScript Usage
-
-```typescript
-import { chromium, Page } from 'playwright';
-import { 
-  findLocator, 
-  getLocator, 
-  createNLPHelper, 
-  FindLocatorResult,
-  NLPHelper,
-  NLPLocatorConfig 
-} from 'playwright-nlp-locator';
-
-async function typedExample(): Promise<void> {
-  const browser = await chromium.launch();
-  const page: Page = await browser.newPage();
-  
-  const config: NLPLocatorConfig = {
-    confidenceThreshold: 0.7,
-    maxElements: 50
-  };
-  
-  const result: FindLocatorResult = await findLocator(page, 'Login button', config);
-  
-  if (result.found && result.confidence >= 0.7) {
-    console.log(`Found: ${result.locator}`);
-  }
-  
-  const nlp: NLPHelper = createNLPHelper(page, config);
-  await nlp.click('Submit button');
-  
-  await browser.close();
-}
+### Drag & Drop
+
+```js
+test('kanban board', async ({ page }) => {
+  const smart = createSmartLocator(page);
+  await page.goto('https://app.example.com/board');
+
+  await smart.dragTo('first task card', 'done column');
+  await smart.waitForVisible('task moved toast');
+});
+```
+
+## Best Practices
+
+**Be specific about element type:**
+```js
+await smart.click('login button');        // good
+await smart.click('button');              // too vague
 ```
 
-## 🤝 Contributing
+**Include context when needed:**
+```js
+await smart.click('delete button in first row');
+await smart.fill('search box in header', 'shoes');
+```
+
+**Use action-appropriate descriptions:**
+```js
+await smart.fill('username', 'Admin');    // finds the input
+await smart.click('username label');       // finds the label
+```
+
+**Reuse the same instance across navigations:**
+```js
+const smart = createSmartLocator(page);
+await page.goto('/login');
+await smart.fill('username', 'Admin');
+await smart.click('login button');
+// navigated to /dashboard — same smart object works
+await smart.click('settings tab');
+```
+
+**Use locate() for multiple actions on same element:**
+```js
+const el = await smart.locate('search box');
+await el.fill('query');
+await el.press('Enter');
+// 1 LLM call instead of 2
+```
+
+## TypeScript
+
+```ts
+import { test } from '@playwright/test';
+import { createSmartLocator, SmartAction, SmartLocator } from 'playwright-genie';
+
+test('typed example', async ({ page }) => {
+  const smart: SmartLocator = createSmartLocator(page);
+
+  const el: SmartAction = await smart.locate('username');
+  await el.fill('Admin');
+
+  const visible: boolean = await smart.isVisible('dashboard');
+  const text: string | null = await smart.getText('heading');
+});
+```
+
+## Debug Mode
+
+```bash
+LLM_LOCATOR_DEBUG=true npx playwright test
+```
+
+This logs:
+- LLM queries and responses
+- Cache hits/misses (memory and disk)
+- Page structure payload sizes
+- Stale cache invalidations
+
+## Security Notes
+
+- The library sends the page's accessibility tree to your configured LLM API
+- Sensitive data visible in the DOM may be sent to the API
+- Use environment variables for API keys — never hardcode them
+- For sensitive environments, use a local LLM (e.g., Ollama)
+
+## Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request.
 
-## 📝 License
+## License
 
-MIT License - see the [LICENSE](LICENSE) file for details.
+MIT License — see the [LICENSE](LICENSE) file for details.
 
-## 🙏 Acknowledgments
+## Acknowledgments
 
-- [Playwright](https://playwright.dev/) - The underlying browser automation framework
-- [Abacus.AI](https://abacus.ai/) - LLM API powering the natural language understanding
+- [Playwright](https://playwright.dev/) — browser automation framework
+- [OpenAI](https://openai.com/) — LLM API support
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) — AI-powered code generation and architecture design

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "playwright-genie",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Find and interact with Playwright elements using natural language descriptions powered by LLM",
   "type": "module",
   "main": "dist/index.cjs",