playwright-genie 1.0.0 → 2.0.0

package/README.md

@@ -1,435 +1,697 @@
-# 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
+- **Adaptive Page Analysis** — automatically switches between ARIA, hybrid, and DOM-only modes based on page accessibility quality
+- **DOM Tree Pipeline** — generates XPath and CSS selectors in-browser for pages with poor accessibility
+- **Smart Caching** — two-tier cache (memory + disk `.locator-cache.json`) to minimize LLM calls
+- **Fallback Locator Chains** — LLM returns multiple locator strategies; if the primary fails, fallbacks are tried automatically
+- **Action-Aware** — `fill('username')` targets the input, not the label
+- **Auto-Retry** — stale cached locators are automatically invalidated and re-resolved
+- **Batch Resolution** — `prefetch()` resolves multiple queries in a single LLM call
+- **iframe Support** — automatically detects and resolves elements inside iframes
+- **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();
+```
+
+## How It Works
+
+When you call `smart.click('login button')`, the library:
+
+1. **Collects page structure** — gathers the ARIA accessibility tree, interactive elements, special attributes (`data-testid`, `placeholder`, `aria-label`), and a full DOM tree with XPath/CSS selectors
+2. **Evaluates ARIA quality** — scores the page as `good`, `sparse`, or `none` based on how many named interactive elements the ARIA tree contains
+3. **Builds an adaptive payload** — selects the best strategy:
+   - **`aria` mode** — rich ARIA tree with good accessibility; uses ARIA snapshot + special elements
+   - **`hybrid` mode** — sparse ARIA; combines the ARIA tree with DOM tree nodes for better coverage
+   - **`dom` mode** — no useful ARIA; sends DOM tree with XPaths and CSS selectors generated in-browser
+4. **Queries the LLM** — sends the payload with your natural language query; the LLM returns a Playwright locator string (e.g., `getByRole('button', { name: 'Login' })`) along with fallback locators
+5. **Validates and caches** — verifies the locator resolves to a real element, caches it to memory and disk, and returns a `SmartAction` for interaction
+6. **Auto-recovers** — if a cached locator goes stale, it's invalidated and re-resolved; if the primary locator fails, fallback locators are tried automatically
+
+## 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 |
+| `actionTimeout` | `number` | `10000` | Timeout for actions in ms |
+
+---
+
+### Interaction Actions
+
+```js
+await smart.click('login button');
+await smart.click('submit', { force: true });
+
+await smart.dblclick('editable cell');
+
+await smart.fill('username', 'Admin');
+await smart.fill('email field', 'a@b.com', { timeout: 5000 });
+
+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');
 ```
 
-## 🚀 Quick Start
+---
+
+### Checkbox & Radio
 
-```javascript
-const { chromium } = require('playwright');
-const { findLocator, createNLPHelper } = require('playwright-nlp-locator');
+```js
+await smart.check('remember me checkbox');
 
-async function main() {
-  const browser = await chromium.launch();
-  const page = await browser.newPage();
-  await page.goto('https://example.com');
+await smart.uncheck('newsletter opt-in');
 
-  // 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
+await smart.setChecked('terms checkbox', 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 browser.close();
-}
+### File Upload
 
-main();
+```js
+await smart.setInputFiles('file upload', '/path/to/file.pdf');
+await smart.setInputFiles('avatar input', ['/img1.png', '/img2.png']);
 ```
 
-## 📖 API Reference
+---
 
-### `findLocator(page, description, options?)`
+### Drag & Drop
 
-Find a Playwright locator using natural language description.
+```js
+const { source, target } = await smart.dragTo('card item', 'drop zone');
+```
+
+---
+
+### Wait Actions
 
-**Parameters:**
-- `page` - Playwright Page object
-- `description` - Natural language description of the element
-- `options` - Optional configuration object
+```js
+await smart.waitForVisible('success toast');
+await smart.waitForVisible('modal', 10000);
 
-**Returns:** `Promise<FindLocatorResult>`
+await smart.waitForHidden('loading spinner');
 
-```javascript
-const result = await findLocator(page, 'email input field');
+await smart.waitForAttached('dynamic table');
 
-// 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
-}
+await smart.waitForDetached('old modal');
+
+await smart.waitFor('element', { state: 'visible', timeout: 5000 });
 ```
 
-### `getLocator(page, description, options?)`
+---
 
-Get an actual Playwright Locator object ready for interaction.
+### State Queries
 
-```javascript
-const { locator, result } = await getLocator(page, 'Submit button');
+```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');
+```
 
-// Use the locator directly
-await locator.click();
-await locator.fill('text');
-const text = await locator.textContent();
+---
+
+### Content Retrieval
+
+```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');
 ```
 
-### `findAllLocators(page, description, options?)`
+---
+
+### Scroll & Visual
 
-Find multiple matching elements for a description.
+```js
+await smart.scrollIntoView('footer section');
 
-```javascript
-const matches = await findAllLocators(page, 'navigation links');
+const buffer = await smart.screenshot('chart area', { path: 'chart.png' });
 
-// 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' }
-]
+await smart.highlight('target element');
 ```
 
-### `createNLPHelper(page, options?)`
+---
+
+### `smart.locate()` — Resolve Once, Act Many Times
+
+When you need multiple actions on the same element, use `locate()` to resolve the locator once:
 
-Create a helper object with natural language methods.
+```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());
 
-```javascript
-const nlp = createNLPHelper(page);
+// Access the raw Playwright locator
+const loc = el.rawLocator;
 
-// 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');
+// 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');
 ```
 
-## ⚙️ 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']
-};
+### `smart.prefetch()` — Batch Resolve
 
-const result = await findLocator(page, 'Submit button', options);
+Pre-resolve multiple locators in a single LLM call to save time and cost:
+
+```js
+await smart.prefetch('username', 'password', 'login button');
+
+// These now hit the cache — no LLM calls
+await smart.fill('username', 'Admin');
+await smart.fill('password', 'secret');
+await smart.click('login button');
 ```
 
-## 🎯 Best Practices for Descriptions
+---
+
+### Cache Management
+
+```js
+smart.clearCache();       // clear in-memory cache only
+smart.clearAllCaches();   // clear both memory + disk (.locator-cache.json)
+```
 
-### ✅ Good Descriptions
+Use `clearCache()` after SPA navigations where the DOM changes significantly (e.g., after login) to force fresh page analysis.
 
-```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');
+## Low-Level API
 
-// Include context when needed
-await nlp.click('Add to cart button for the first product');
-await nlp.type('Search box in the header', 'shoes');
+For advanced use cases, you can use the lower-level exports directly.
 
-// Use visual or functional descriptions
-await nlp.click('Red cancel button');
-await nlp.click('Hamburger menu icon');
-await nlp.click('Close modal X button');
+### `findLocator(page, query, options?)`
+
+Resolves a single natural language query to a Playwright locator string without performing any action.
+
+```js
+import { findLocator } from 'playwright-genie';
+
+const result = await findLocator(page, 'submit button');
+console.log(result);
+// {
+//   found: true,
+//   strategy: 'role',
+//   locatorString: "getByRole('button', { name: 'Submit' })",
+//   confidence: 0.95,
+//   fallbackLocators: ["getByTestId('submit-btn')", "locator('#submit')"],
+//   isInFrame: false,
+//   frameSelector: null
+// }
+```
+
+### `findAllMatches(page, query, options?)`
+
+Returns an array of all matching locator results for a query.
+
+```js
+import { findAllMatches } from 'playwright-genie';
+
+const matches = await findAllMatches(page, 'navigation link');
+```
+
+### `getPageStructure(page, forceRefresh?)`
+
+Returns the full page structure used for LLM resolution. Useful for debugging or building custom pipelines.
+
+```js
+import { getPageStructure } from 'playwright-genie';
+
+const structure = await getPageStructure(page);
+console.log(structure.mainFrame.ariaQuality); // 'good' | 'sparse' | 'none'
+console.log(structure.mainFrame.ariaTree);    // ARIA snapshot (YAML string)
+console.log(structure.mainFrame.domTree);     // Array of DOM nodes with XPath/CSS
+console.log(structure.mainFrame.interactiveElements); // Interactive element metadata
+console.log(structure.mainFrame.specialElements);     // Elements with data-testid, etc.
+console.log(structure.frames);                // iframe structures
+```
+
+### `resolveLocator(page, query, options?)`
+
+Low-level resolver that checks memory cache → disk cache → LLM. Returns the raw result object without creating a Playwright locator.
+
+```js
+import { resolveLocator } from 'playwright-genie';
+
+const result = await resolveLocator(page, 'login button', { action: 'click' });
+// result.source is 'memory', 'disk', or 'llm'
 ```
 
-### ❌ Avoid Vague Descriptions
+### `getLocator(page, query, options?)`
 
-```javascript
-// Too vague - could match multiple elements
-await nlp.click('button');
-await nlp.type('input', 'text');
+Resolves a query and returns both the Playwright `Locator` object and the result metadata. Handles stale cache invalidation and fallback chains.
 
-// Better alternatives:
-await nlp.click('primary submit button');
-await nlp.type('username input', 'text');
+```js
+import { getLocator } from 'playwright-genie';
+
+const { locator, result } = await getLocator(page, 'email input', { action: 'fill' });
+await locator.fill('user@example.com');
 ```
 
-## 📚 Complete Examples
+### `clearCache()` / `clearAllCaches()`
 
-### Example 1: Login Form Automation
+Module-level cache clearing functions.
 
-```javascript
-const { chromium } = require('playwright');
-const { createNLPHelper } = require('playwright-nlp-locator');
+```js
+import { clearCache, clearAllCaches } from 'playwright-genie';
 
-async function loginAutomation() {
-  const browser = await chromium.launch();
-  const page = await browser.newPage();
-  
+clearCache();       // memory only
+clearAllCaches();   // memory + disk
+```
+
+## Adaptive Page Analysis
+
+The library automatically adapts to the accessibility quality of each page:
+
+| ARIA Quality | Criteria | Mode | What Gets Sent to LLM |
+|---|---|---|---|
+| **`good`** | ARIA tree has 3+ named interactive elements, 20+ lines | `aria` | Trimmed ARIA tree + special elements + interactive elements |
+| **`sparse`** | ARIA tree exists but fewer named elements than the page has | `hybrid` | ARIA tree + DOM tree nodes (XPath/CSS) + interactive elements |
+| **`none`** | ARIA tree has < 5 lines or is missing | `dom` | DOM tree with XPaths and CSS selectors + interactive elements |
+
+### DOM Tree Pipeline
+
+For pages with poor or no accessibility markup, the library walks the DOM in-browser and:
+
+- Traverses up to **300 visible nodes** (headings, links, buttons, inputs, landmarks, etc.)
+- Generates **XPath** for each node (e.g., `//*[@id="login"]`, `//form/div[2]/input[1]`)
+- Generates **unique CSS selectors** (e.g., `#login`, `[data-testid="submit"]`, `button.primary`)
+- Extracts text content, ARIA labels, placeholders, `data-testid` attributes, and parent context
+- Filters nodes by **relevance scoring** against your query before sending to the LLM
+
+This means the library works on any page — not just accessible ones.
+
+## Caching
+
+**playwright-genie** uses a two-level cache to minimize LLM calls:
+
+1. **Memory cache** — instant lookups within the same test run
+2. **Disk cache** (`.locator-cache.json`) — persists across runs
+
+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), the library:
+1. Tries **fallback locators** returned by the LLM
+2. If all fallbacks fail, **invalidates the cache** and re-queries the LLM with fresh page structure
+
+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();
-}
-```
-
-### Example 2: E-commerce Shopping Flow
-
-```javascript
-async function shoppingFlow() {
-  const browser = await chromium.launch();
-  const page = await browser.newPage();
-  const nlp = createNLPHelper(page);
-  
+
+  await smart.click('sign in button');
+  await smart.waitForVisible('dashboard heading');
+
+  const welcome = await smart.getText('welcome message');
+  expect(welcome).toContain('admin');
+});
+```
+
+### E-commerce Flow
+
+```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
-
-```javascript
-const { findLocator, getLocator } = require('playwright-nlp-locator');
-
-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.fill('search bar', 'wireless headphones');
+  await smart.press('search bar', 'Enter');
+  await smart.waitForVisible('product list');
+
+  await smart.click('first product card');
+  await smart.select('size dropdown', 'Medium');
+  await smart.click('add to cart button');
+
+  await smart.waitForVisible('cart badge');
+  const count = await smart.getText('cart badge');
+  expect(count).toBe('1');
+});
 ```
 
-### Example 4: Dynamic Content Handling
+### SPA Navigation with Cache Clearing
 
-```javascript
-async function handleDynamicContent() {
-  const browser = await chromium.launch();
-  const page = await browser.newPage();
-  const nlp = createNLPHelper(page);
-  
+```js
+test('SPA login and navigate', async ({ page }) => {
+  const smart = createSmartLocator(page);
+  await page.goto('https://spa-app.com/login');
+
+  await smart.fill('username', 'admin');
+  await smart.fill('password', 'secret');
+  await smart.click('login button');
+
+  // After SPA navigation, clear cache to force fresh page analysis
+  await page.waitForURL('**/dashboard');
+  smart.clearCache();
+
+  await smart.click('settings tab');
+  await smart.waitForVisible('settings panel');
+});
+```
+
+### Batch Pre-fetch for Performance
+
+```js
+test('prefetch for faster tests', async ({ page }) => {
+  const smart = createSmartLocator(page);
+  await page.goto('https://myapp.com/form');
+
+  // Resolve all locators in one LLM call
+  await smart.prefetch(
+    'first name input',
+    'last name input',
+    'email field',
+    'phone number',
+    'submit button'
+  );
+
+  // All cached — zero LLM calls from here
+  await smart.fill('first name input', 'John');
+  await smart.fill('last name input', 'Doe');
+  await smart.fill('email field', 'john@example.com');
+  await smart.fill('phone number', '555-0123');
+  await smart.click('submit button');
+});
+```
+
+### Dynamic Content & Modals
+
+```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');
-  }
-  
-  // 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();
-}
-```
-
-## 🔧 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);
-}
-```
-
-## 🔒 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}`);
+
+  if (await smart.exists('cookie consent popup')) {
+    await smart.click('accept cookies button');
+    await smart.waitForHidden('cookie consent popup');
   }
-  
-  const nlp: NLPHelper = createNLPHelper(page, config);
-  await nlp.click('Submit 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');
+});
 ```
 
-## 🤝 Contributing
+### Using Low-Level API for Debugging
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+```js
+import { getPageStructure, findLocator } from 'playwright-genie';
+
+test('debug locator resolution', async ({ page }) => {
+  await page.goto('https://myapp.com');
+
+  // Inspect page analysis
+  const structure = await getPageStructure(page);
+  console.log('ARIA quality:', structure.mainFrame.ariaQuality);
+  console.log('DOM nodes:', structure.mainFrame.domTree.length);
+  console.log('Interactive elements:', structure.mainFrame.interactiveElements.length);
+
+  // See what the LLM resolves without acting
+  const result = await findLocator(page, 'submit button');
+  console.log('Strategy:', result.strategy);
+  console.log('Locator:', result.locatorString);
+  console.log('Fallbacks:', result.fallbackLocators);
+});
+```
+
+## Exports
+
+```js
+import {
+  createSmartLocator,   // Main entry — creates smart locator with 40+ action methods
+  findLocator,          // Resolve a query to a locator string (no action)
+  findAllMatches,       // Get all matching locator results
+  getPageStructure,     // Get the full page structure (ARIA + DOM + interactive elements)
+  getLocator,           // Resolve + validate + create Playwright Locator object
+  resolveLocator,       // Low-level: cache lookup → LLM resolution
+  clearCache,           // Clear in-memory cache
+  clearAllCaches,       // Clear memory + disk cache
+  SmartAction,          // Class wrapping a Playwright Locator with 40+ methods
+  chatCompletion,       // Direct LLM call (for custom pipelines)
+  getConfig,            // Get current LLM configuration
+  loadDiskCache,        // Load disk cache manually
+  invalidateDiskEntry,  // Invalidate a specific disk cache entry
+} from 'playwright-genie';
+```
+
+## Best Practices
+
+**Be specific about element type:**
+```js
+await smart.click('login button');        // good
+await smart.click('button');              // too vague
+```
+
+**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
+```
 
-## 📝 License
+**Use prefetch() for forms and multi-element pages:**
+```js
+await smart.prefetch('name', 'email', 'password', 'submit');
+// 1 LLM call instead of 4
+```
+
+**Clear cache after SPA navigation:**
+```js
+await page.waitForURL('**/dashboard');
+smart.clearCache();
+```
+
+## 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
 
-MIT License - see the [LICENSE](LICENSE) file for details.
+```bash
+LLM_LOCATOR_DEBUG=true npx playwright test
+```
+
+This logs:
+- Payload mode selected (`aria`/`hybrid`/`dom`) and payload size
+- LLM queries and responses
+- Cache hits/misses (memory and disk)
+- Stale cache invalidations and fallback attempts
+- Page structure collection timing
+
+## Environment Variables
+
+| Variable | Description |
+|---|---|
+| `LLM_API_KEY` | API key for LLM provider |
+| `LLM_BASE_URL` | Base URL for OpenAI-compatible API |
+| `LLM_MODEL` | Model name (e.g., `gpt-4o-mini`) |
+| `OPENAI_API_KEY` | Fallback API key |
+| `ANTHROPIC_API_KEY` | Fallback API key |
+| `ROUTELLM_API_KEY` | Fallback API key |
+| `LOCATOR_CACHE_FILE` | Custom path for disk cache file |
+| `LLM_LOCATOR_DEBUG` | Set to `true` to enable debug logging |
+
+## Security Notes
+
+- The library sends the page's accessibility tree and/or DOM structure 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.
 
-## 🙏 Acknowledgments
+## License
 
-- [Playwright](https://playwright.dev/) - The underlying browser automation framework
-- [Abacus.AI](https://abacus.ai/) - LLM API powering the natural language understanding
+MIT License — see the [LICENSE](LICENSE) file for details.