semantic-playwright 0.1.0

package/README.md

@@ -0,0 +1,220 @@
+# semantic-playwright
+
+**Click by description, not selectors.**
+
+A Playwright extension for semantic element targeting. Write resilient tests that survive website redesigns.
+
+## Installation
+
+```bash
+npm install semantic-playwright playwright
+```
+
+## Quick Start
+
+```typescript
+import { test } from '@playwright/test';
+import { semantic } from 'semantic-playwright';
+
+test('login flow', async ({ page }) => {
+  await page.goto('https://example.com/login');
+
+  const s = semantic(page);
+
+  // Click and fill by description - no CSS selectors needed
+  await s.fill('email input', 'user@example.com');
+  await s.fill('password field', 'secret123');
+  await s.click('sign in button');
+
+  // Wait for success
+  await s.waitFor('welcome message');
+});
+```
+
+## Why?
+
+Modern web UIs change constantly. CSS selectors like `#main-nav > ul > li:nth-child(3) > a.btn-primary` break the moment a designer moves a button. This library provides **self-healing locators** that target elements by their semantic purpose.
+
+```typescript
+// Fragile - breaks on redesign
+await page.click('#nav-signin-btn');
+
+// Resilient - survives redesign
+await s.click('sign in button');
+```
+
+## How It Works
+
+The semantic engine classifies DOM elements using multiple signals:
+- **ARIA roles**: `role="button"`, `role="navigation"`
+- **Semantic HTML**: `<nav>`, `<main>`, `<button>`, `<form>`
+- **Text content**: "Sign In", "Submit", "Search"
+- **Class patterns**: `btn`, `nav`, `form-input`
+- **Context**: Element inside `<nav>` likely navigation-related
+
+**No LLM required.** Pure heuristic matching. Fast, local, privacy-preserving.
+
+## API
+
+### `semantic(page)`
+
+Wrap a Playwright page with semantic methods:
+
+```typescript
+const s = semantic(page);
+```
+
+### `s.click(description, options?)`
+
+Click an element by description:
+
+```typescript
+await s.click('submit button');
+await s.click('login', { purposeHint: 'action' });
+```
+
+### `s.fill(description, value, options?)`
+
+Fill a form field by description:
+
+```typescript
+await s.fill('email input', 'test@example.com');
+await s.fill('search box', 'playwright');
+```
+
+### `s.locator(description, options?)`
+
+Get a Playwright Locator for chaining:
+
+```typescript
+const btn = await s.locator('checkout button');
+await btn.hover();
+await btn.click();
+```
+
+### `s.analyze(includeUnknown?)`
+
+Analyze page structure:
+
+```typescript
+const { elements, summary } = await s.analyze();
+console.log(summary);
+// { navigation: 12, action: 8, form: 5, content: 20, data: 3, unknown: 0 }
+```
+
+### `s.query(category, textQuery?)`
+
+Find elements by category:
+
+```typescript
+const buttons = await s.query('action');
+const searchInputs = await s.query('form', 'search');
+```
+
+### `s.findAll(description, options?)`
+
+Find all matching elements with scores:
+
+```typescript
+const matches = await s.findAll('submit');
+for (const { locator, score, text } of matches) {
+  console.log(`${text}: ${score}`);
+}
+```
+
+### `s.waitFor(description, options?)`
+
+Wait for element to appear:
+
+```typescript
+await s.waitFor('success notification', { timeout: 10000 });
+```
+
+## Categories
+
+| Category | Description | Examples |
+|----------|-------------|----------|
+| `navigation` | Navigation elements | Nav bars, menus, breadcrumbs |
+| `action` | Interactive actions | Buttons, CTAs, links styled as buttons |
+| `form` | Form inputs | Text fields, selects, checkboxes |
+| `content` | Main content | Articles, headings, paragraphs |
+| `data` | Data display | Tables, lists, grids |
+
+## Options
+
+```typescript
+interface SemanticOptions {
+  purposeHint?: 'navigation' | 'action' | 'form' | 'content' | 'data';
+  timeout?: number;    // Default: 5000ms
+  minScore?: number;   // Default: 20
+}
+```
+
+## Architecture
+
+```
+src/
+├── index.ts           # Main API - SemanticPage wrapper
+├── semantic-mapper.ts # Classification engine & JS generators
+```
+
+**Key design decisions:**
+- Scripts execute in browser context via `page.evaluate()`
+- Classification is entirely heuristic-based (no external calls)
+- Selectors generated are full CSS paths for reliability
+- Scoring system prefers exact matches, falls back gracefully
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test
+```
+
+### Testing Philosophy
+
+Tests should use real websites to validate resilience:
+1. Test against sites that redesign frequently
+2. Snapshot selectors, verify semantic descriptions still work after updates
+3. Compare failure rates: CSS selectors vs semantic descriptions
+
+## Roadmap
+
+### v0.1.0 (Current)
+- [x] Core semantic classification engine
+- [x] `semantic()` page wrapper
+- [x] `click()`, `fill()`, `locator()` methods
+- [x] `analyze()` and `query()` methods
+- [x] `findAll()` and `waitFor()` methods
+
+### v0.2.0
+- [ ] Playwright Test fixtures (`useSemanticPage`)
+- [ ] Custom matchers (`expect(s).toHaveElement('login button')`)
+- [ ] Confidence thresholds configuration
+- [ ] Debug mode with match explanations
+
+### v0.3.0
+- [ ] Learning/correction persistence
+- [ ] Domain-specific overrides
+- [ ] Screenshot-on-failure with element highlighting
+- [ ] Playwright Reporter integration
+
+### v1.0.0
+- [ ] Comprehensive test suite
+- [ ] Performance benchmarks
+- [ ] Documentation site
+- [ ] VS Code extension for selector conversion
+
+## Prior Art
+
+This library is inspired by and aims to improve upon:
+- **Browser-Use**: AI agent browser automation (requires LLM)
+- **Healenium**: Self-healing Selenium (Java-focused)
+- **Test.ai**: AI-powered testing (SaaS, expensive)
+
+Our differentiator: **No LLM required**. Fast, local, free.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Semantic Playwright - Click by description, not selectors
+ *
+ * Extends Playwright with semantic element targeting that survives
+ * website redesigns. No LLM required - pure heuristic matching.
+ *
+ * @example
+ * ```typescript
+ * import { semantic } from 'semantic-playwright';
+ *
+ * // Wrap your page
+ * const s = semantic(page);
+ *
+ * // Click by description instead of selector
+ * await s.click('login button');
+ * await s.fill('email input', 'user@example.com');
+ *
+ * // Or use locators
+ * const loginBtn = await s.locator('login button');
+ * await loginBtn.click();
+ * ```
+ */
+import type { Page, Locator } from 'playwright';
+import { SemanticCategory, SemanticElement, ClickResult, QueryResult } from './semantic-mapper';
+export { SemanticCategory, SemanticElement, ClickResult, QueryResult, } from './semantic-mapper';
+/**
+ * Options for semantic operations
+ */
+export interface SemanticOptions {
+    /** Hint about element purpose: navigation, action, form, content, data */
+    purposeHint?: SemanticCategory;
+    /** Timeout in milliseconds (default: 5000) */
+    timeout?: number;
+    /** Minimum score required for a match (default: 20) */
+    minScore?: number;
+}
+/**
+ * Options for semantic fill operations
+ */
+export interface FillOptions extends SemanticOptions {
+    /** Clear existing content before filling (default: true) */
+    clear?: boolean;
+}
+/**
+ * Result of a semantic analysis
+ */
+export interface AnalysisResult {
+    elements: SemanticElement[];
+    summary: {
+        navigation: number;
+        action: number;
+        form: number;
+        content: number;
+        data: number;
+        unknown: number;
+    };
+}
+/**
+ * Semantic page wrapper providing resilient element targeting
+ */
+export interface SemanticPage {
+    /** The underlying Playwright page */
+    readonly page: Page;
+    /**
+     * Analyze the page and classify all elements by semantic purpose
+     * @param includeUnknown - Include elements with unknown category
+     * @returns Analysis result with elements and summary counts
+     */
+    analyze(includeUnknown?: boolean): Promise<AnalysisResult>;
+    /**
+     * Query elements by semantic category
+     * @param category - Element category to find
+     * @param textQuery - Optional text to filter by
+     * @returns Array of matching elements
+     */
+    query(category: SemanticCategory, textQuery?: string): Promise<QueryResult[]>;
+    /**
+     * Click an element by semantic description
+     * @param description - Natural language description (e.g., "login button")
+     * @param options - Optional targeting options
+     * @returns Result with clicked status and matched selector
+     */
+    click(description: string, options?: SemanticOptions): Promise<ClickResult>;
+    /**
+     * Fill a form field by semantic description
+     * @param description - Natural language description (e.g., "email input")
+     * @param value - Value to fill
+     * @param options - Optional fill options
+     * @returns Result with filled status and matched selector
+     */
+    fill(description: string, value: string, options?: FillOptions): Promise<{
+        filled: boolean;
+        selector?: string;
+        error?: string;
+    }>;
+    /**
+     * Get a Playwright Locator for an element by semantic description
+     * Useful when you need to chain Playwright methods
+     * @param description - Natural language description
+     * @param options - Optional targeting options
+     * @returns Playwright Locator for the matched element
+     */
+    locator(description: string, options?: SemanticOptions): Promise<Locator>;
+    /**
+     * Find all clickable elements matching a description
+     * @param description - Natural language description
+     * @param options - Optional targeting options
+     * @returns Array of matching locators with scores
+     */
+    findAll(description: string, options?: SemanticOptions): Promise<Array<{
+        locator: Locator;
+        score: number;
+        text: string | null;
+    }>>;
+    /**
+     * Wait for an element matching the description to appear
+     * @param description - Natural language description
+     * @param options - Optional targeting options
+     * @returns Locator for the appeared element
+     */
+    waitFor(description: string, options?: SemanticOptions): Promise<Locator>;
+}
+/**
+ * Create a semantic wrapper around a Playwright page
+ * @param page - Playwright Page instance
+ * @returns SemanticPage with semantic targeting methods
+ */
+export declare function semantic(page: Page): SemanticPage;
+export default semantic;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,WAAW,EACX,WAAW,EAKZ,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,WAAW,EACX,WAAW,GACZ,MAAM,mBAAmB,CAAC;AAE3B;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,0EAA0E;IAC1E,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAC/B,8CAA8C;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,WAAY,SAAQ,eAAe;IAClD,4DAA4D;IAC5D,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,OAAO,EAAE;QACP,UAAU,EAAE,MAAM,CAAC;QACnB,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,qCAAqC;IACrC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IAEpB;;;;OAIG;IACH,OAAO,CAAC,cAAc,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAE3D;;;;;OAKG;IACH,KAAK,CAAC,QAAQ,EAAE,gBAAgB,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IAE9E;;;;;OAKG;IACH,KAAK,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAE5E;;;;;;OAMG;IACH,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAEjI;;;;;;OAMG;IACH,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAE1E;;;;;OAKG;IACH,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC,CAAC;IAElI;;;;;OAKG;IACH,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC3E;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,YAAY,CAEjD;AAiSD,eAAe,QAAQ,CAAC"}

package/dist/index.js

@@ -0,0 +1,296 @@
+"use strict";
+/**
+ * Semantic Playwright - Click by description, not selectors
+ *
+ * Extends Playwright with semantic element targeting that survives
+ * website redesigns. No LLM required - pure heuristic matching.
+ *
+ * @example
+ * ```typescript
+ * import { semantic } from 'semantic-playwright';
+ *
+ * // Wrap your page
+ * const s = semantic(page);
+ *
+ * // Click by description instead of selector
+ * await s.click('login button');
+ * await s.fill('email input', 'user@example.com');
+ *
+ * // Or use locators
+ * const loginBtn = await s.locator('login button');
+ * await loginBtn.click();
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.semantic = semantic;
+const semantic_mapper_1 = require("./semantic-mapper");
+/**
+ * Create a semantic wrapper around a Playwright page
+ * @param page - Playwright Page instance
+ * @returns SemanticPage with semantic targeting methods
+ */
+function semantic(page) {
+    return new SemanticPageImpl(page);
+}
+/**
+ * Implementation of SemanticPage
+ */
+class SemanticPageImpl {
+    constructor(page) {
+        this.page = page;
+    }
+    async analyze(includeUnknown = false) {
+        const script = (0, semantic_mapper_1.generateAnalysisScript)(includeUnknown);
+        const elements = await this.page.evaluate(script);
+        const summary = {
+            navigation: 0,
+            action: 0,
+            form: 0,
+            content: 0,
+            data: 0,
+            unknown: 0,
+        };
+        for (const el of elements) {
+            summary[el.category]++;
+        }
+        return { elements, summary };
+    }
+    async query(category, textQuery) {
+        const script = (0, semantic_mapper_1.generateQueryScript)(category, textQuery);
+        return await this.page.evaluate(script);
+    }
+    async click(description, options = {}) {
+        const { purposeHint, timeout = 5000, minScore = 20 } = options;
+        // Generate and execute the click script
+        const script = (0, semantic_mapper_1.generateClickScript)(description, purposeHint);
+        // Wait for page to be ready
+        await this.page.waitForLoadState('domcontentloaded', { timeout });
+        const result = await this.page.evaluate(script);
+        // Validate minimum score
+        if (result.clicked && result.score !== undefined && result.score < minScore) {
+            return {
+                clicked: false,
+                error: `Match score ${result.score} below minimum ${minScore}`,
+            };
+        }
+        return result;
+    }
+    async fill(description, value, options = {}) {
+        const { timeout = 5000, clear = true } = options;
+        // Wait for page to be ready
+        await this.page.waitForLoadState('domcontentloaded', { timeout });
+        const script = (0, semantic_mapper_1.generateFillScript)(description, value);
+        const result = await this.page.evaluate(script);
+        if (result.filled && result.selector && clear) {
+            // The script already sets the value, but we can use Playwright's fill
+            // for better event handling if needed
+            try {
+                const element = await this.page.$(result.selector);
+                if (element) {
+                    await element.fill(value);
+                }
+            }
+            catch {
+                // Script already filled it, ignore fill errors
+            }
+        }
+        return {
+            filled: result.filled,
+            selector: result.selector,
+            error: result.error,
+        };
+    }
+    async locator(description, options = {}) {
+        const { purposeHint, timeout = 5000 } = options;
+        // First, find the element using our semantic script
+        const findScript = `
+(function() {
+  'use strict';
+
+  const searchText = ${JSON.stringify(description.toLowerCase())};
+  const purposeHint = ${JSON.stringify(purposeHint || '')};
+
+  function getUniqueSelector(el) {
+    if (el.id) return '#' + CSS.escape(el.id);
+    let path = [];
+    while (el && el.nodeType === Node.ELEMENT_NODE) {
+      let selector = el.tagName.toLowerCase();
+      if (el.id) { selector = '#' + CSS.escape(el.id); path.unshift(selector); break; }
+      let sibling = el, nth = 1;
+      while (sibling = sibling.previousElementSibling) { if (sibling.tagName === el.tagName) nth++; }
+      if (nth > 1 || el.nextElementSibling?.tagName === el.tagName) selector += ':nth-of-type(' + nth + ')';
+      path.unshift(selector);
+      el = el.parentElement;
+    }
+    return path.join(' > ');
+  }
+
+  function classify(el) {
+    const tag = el.tagName.toLowerCase();
+    const role = el.getAttribute('role');
+    if (tag === 'nav' || role === 'navigation') return 'navigation';
+    if (tag === 'button' || role === 'button' || el.type === 'submit') return 'action';
+    if (['input', 'textarea', 'select', 'form'].includes(tag)) return 'form';
+    if (tag === 'table' || role === 'table') return 'data';
+    if (['main', 'article', 'h1', 'p'].includes(tag)) return 'content';
+    return 'unknown';
+  }
+
+  function scoreMatch(el) {
+    const text = (el.textContent || '').toLowerCase();
+    const ariaLabel = (el.getAttribute('aria-label') || '').toLowerCase();
+    const title = (el.getAttribute('title') || '').toLowerCase();
+    const id = (el.id || '').toLowerCase();
+    const classes = Array.from(el.classList).join(' ').toLowerCase();
+    const placeholder = (el.placeholder || '').toLowerCase();
+    const name = (el.name || '').toLowerCase();
+
+    let score = 0;
+
+    if (text.trim() === searchText || ariaLabel === searchText) score += 100;
+    else if (text.includes(searchText) || ariaLabel.includes(searchText)) score += 50;
+    if (title.includes(searchText)) score += 30;
+    if (placeholder.includes(searchText)) score += 40;
+    if (id.includes(searchText.replace(/\\s+/g, '-'))) score += 25;
+    if (name.includes(searchText.replace(/\\s+/g, '_'))) score += 25;
+    if (classes.includes(searchText.replace(/\\s+/g, '-'))) score += 20;
+
+    if (purposeHint && classify(el) === purposeHint) score += 40;
+
+    return score;
+  }
+
+  const candidates = document.querySelectorAll('a, button, [role="button"], input, textarea, select, [onclick], [tabindex]');
+
+  let bestMatch = null;
+  let bestScore = 0;
+
+  candidates.forEach(el => {
+    const style = getComputedStyle(el);
+    if (style.display === 'none' || style.visibility === 'hidden') return;
+
+    const score = scoreMatch(el);
+    if (score > bestScore) {
+      bestScore = score;
+      bestMatch = el;
+    }
+  });
+
+  if (bestMatch && bestScore >= 20) {
+    return { found: true, selector: getUniqueSelector(bestMatch), score: bestScore };
+  }
+
+  return { found: false, error: 'No matching element found' };
+})()`;
+        await this.page.waitForLoadState('domcontentloaded', { timeout });
+        const result = await this.page.evaluate(findScript);
+        if (!result.found || !result.selector) {
+            throw new Error(`Semantic locator failed: ${result.error || 'No matching element found'}`);
+        }
+        return this.page.locator(result.selector);
+    }
+    async findAll(description, options = {}) {
+        const { purposeHint, timeout = 5000, minScore = 20 } = options;
+        const findAllScript = `
+(function() {
+  'use strict';
+
+  const searchText = ${JSON.stringify(description.toLowerCase())};
+  const purposeHint = ${JSON.stringify(purposeHint || '')};
+  const minScore = ${minScore};
+
+  function getUniqueSelector(el) {
+    if (el.id) return '#' + CSS.escape(el.id);
+    let path = [];
+    while (el && el.nodeType === Node.ELEMENT_NODE) {
+      let selector = el.tagName.toLowerCase();
+      if (el.id) { selector = '#' + CSS.escape(el.id); path.unshift(selector); break; }
+      let sibling = el, nth = 1;
+      while (sibling = sibling.previousElementSibling) { if (sibling.tagName === el.tagName) nth++; }
+      if (nth > 1 || el.nextElementSibling?.tagName === el.tagName) selector += ':nth-of-type(' + nth + ')';
+      path.unshift(selector);
+      el = el.parentElement;
+    }
+    return path.join(' > ');
+  }
+
+  function classify(el) {
+    const tag = el.tagName.toLowerCase();
+    const role = el.getAttribute('role');
+    if (tag === 'nav' || role === 'navigation') return 'navigation';
+    if (tag === 'button' || role === 'button' || el.type === 'submit') return 'action';
+    if (['input', 'textarea', 'select', 'form'].includes(tag)) return 'form';
+    if (tag === 'table' || role === 'table') return 'data';
+    if (['main', 'article', 'h1', 'p'].includes(tag)) return 'content';
+    return 'unknown';
+  }
+
+  function scoreMatch(el) {
+    const text = (el.textContent || '').toLowerCase();
+    const ariaLabel = (el.getAttribute('aria-label') || '').toLowerCase();
+    const title = (el.getAttribute('title') || '').toLowerCase();
+    const id = (el.id || '').toLowerCase();
+    const classes = Array.from(el.classList).join(' ').toLowerCase();
+
+    let score = 0;
+
+    if (text.trim() === searchText || ariaLabel === searchText) score += 100;
+    else if (text.includes(searchText) || ariaLabel.includes(searchText)) score += 50;
+    if (title.includes(searchText)) score += 30;
+    if (id.includes(searchText.replace(/\\s+/g, '-'))) score += 25;
+    if (classes.includes(searchText.replace(/\\s+/g, '-'))) score += 20;
+
+    if (purposeHint && classify(el) === purposeHint) score += 40;
+
+    return score;
+  }
+
+  const candidates = document.querySelectorAll('a, button, [role="button"], input, textarea, select, [onclick], [tabindex]');
+  const matches = [];
+
+  candidates.forEach(el => {
+    const style = getComputedStyle(el);
+    if (style.display === 'none' || style.visibility === 'hidden') return;
+
+    const score = scoreMatch(el);
+    if (score >= minScore) {
+      matches.push({
+        selector: getUniqueSelector(el),
+        score: score,
+        text: el.textContent?.trim().substring(0, 100) || null
+      });
+    }
+  });
+
+  return matches.sort((a, b) => b.score - a.score);
+})()`;
+        await this.page.waitForLoadState('domcontentloaded', { timeout });
+        const results = await this.page.evaluate(findAllScript);
+        return results.map(r => ({
+            locator: this.page.locator(r.selector),
+            score: r.score,
+            text: r.text,
+        }));
+    }
+    async waitFor(description, options = {}) {
+        const { timeout = 30000 } = options;
+        const startTime = Date.now();
+        while (Date.now() - startTime < timeout) {
+            try {
+                const locator = await this.locator(description, { ...options, timeout: 1000 });
+                const isVisible = await locator.isVisible();
+                if (isVisible) {
+                    return locator;
+                }
+            }
+            catch {
+                // Element not found yet, continue waiting
+            }
+            await this.page.waitForTimeout(100);
+        }
+        throw new Error(`Timeout waiting for element: "${description}"`);
+    }
+}
+// Default export for convenience
+exports.default = semantic;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;;AA+HH,4BAEC;AA9HD,uDAS2B;AA8G3B;;;;GAIG;AACH,SAAgB,QAAQ,CAAC,IAAU;IACjC,OAAO,IAAI,gBAAgB,CAAC,IAAI,CAAC,CAAC;AACpC,CAAC;AAED;;GAEG;AACH,MAAM,gBAAgB;IACpB,YAA4B,IAAU;QAAV,SAAI,GAAJ,IAAI,CAAM;IAAG,CAAC;IAE1C,KAAK,CAAC,OAAO,CAAC,iBAA0B,KAAK;QAC3C,MAAM,MAAM,GAAG,IAAA,wCAAsB,EAAC,cAAc,CAAC,CAAC;QACtD,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAsB,CAAC;QAEvE,MAAM,OAAO,GAAG;YACd,UAAU,EAAE,CAAC;YACb,MAAM,EAAE,CAAC;YACT,IAAI,EAAE,CAAC;YACP,OAAO,EAAE,CAAC;YACV,IAAI,EAAE,CAAC;YACP,OAAO,EAAE,CAAC;SACX,CAAC;QAEF,KAAK,MAAM,EAAE,IAAI,QAAQ,EAAE,CAAC;YAC1B,OAAO,CAAC,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC;QACzB,CAAC;QAED,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;IAC/B,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,QAA0B,EAAE,SAAkB;QACxD,MAAM,MAAM,GAAG,IAAA,qCAAmB,EAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;QACxD,OAAO,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAkB,CAAC;IAC3D,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,WAAmB,EAAE,UAA2B,EAAE;QAC5D,MAAM,EAAE,WAAW,EAAE,OAAO,GAAG,IAAI,EAAE,QAAQ,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC;QAE/D,wCAAwC;QACxC,MAAM,MAAM,GAAG,IAAA,qCAAmB,EAAC,WAAW,EAAE,WAAW,CAAC,CAAC;QAE7D,4BAA4B;QAC5B,MAAM,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,kBAAkB,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;QAElE,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAgB,CAAC;QAE/D,yBAAyB;QACzB,IAAI,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,KAAK,KAAK,SAAS,IAAI,MAAM,CAAC,KAAK,GAAG,QAAQ,EAAE,CAAC;YAC5E,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,KAAK,EAAE,eAAe,MAAM,CAAC,KAAK,kBAAkB,QAAQ,EAAE;aAC/D,CAAC;QACJ,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,WAAmB,EAAE,KAAa,EAAE,UAAuB,EAAE;QACtE,MAAM,EAAE,OAAO,GAAG,IAAI,EAAE,KAAK,GAAG,IAAI,EAAE,GAAG,OAAO,CAAC;QAEjD,4BAA4B;QAC5B,MAAM,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,kBAAkB,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;QAElE,MAAM,MAAM,GAAG,IAAA,oCAAkB,EAAC,WAAW,EAAE,KAAK,CAAC,CAAC;QACtD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAA2E,CAAC;QAE1H,IAAI,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,QAAQ,IAAI,KAAK,EAAE,CAAC;YAC9C,sEAAsE;YACtE,sCAAsC;YACtC,IAAI,CAAC;gBACH,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;gBACnD,IAAI,OAAO,EAAE,CAAC;oBACZ,MAAM,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;gBAC5B,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,+CAA+C;YACjD,CAAC;QACH,CAAC;QAED,OAAO;YACL,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,KAAK,EAAE,MAAM,CAAC,KAAK;SACpB,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,WAAmB,EAAE,UAA2B,EAAE;QAC9D,MAAM,EAAE,WAAW,EAAE,OAAO,GAAG,IAAI,EAAE,GAAG,OAAO,CAAC;QAEhD,oDAAoD;QACpD,MAAM,UAAU,GAAG;;;;uBAIA,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,WAAW,EAAE,CAAC;wBACxC,IAAI,CAAC,SAAS,CAAC,WAAW,IAAI,EAAE,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAyEpD,CAAC;QAEF,MAAM,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,kBAAkB,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;QAElE,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,UAAU,CAA0E,CAAC;QAE7H,IAAI,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;YACtC,MAAM,IAAI,KAAK,CAAC,4BAA4B,MAAM,CAAC,KAAK,IAAI,2BAA2B,EAAE,CAAC,CAAC;QAC7F,CAAC;QAED,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC5C,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,WAAmB,EAAE,UAA2B,EAAE;QAC9D,MAAM,EAAE,WAAW,EAAE,OAAO,GAAG,IAAI,EAAE,QAAQ,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC;QAE/D,MAAM,aAAa,GAAG;;;;uBAIH,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,WAAW,EAAE,CAAC;wBACxC,IAAI,CAAC,SAAS,CAAC,WAAW,IAAI,EAAE,CAAC;qBACpC,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAkExB,CAAC;QAEF,MAAM,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,kBAAkB,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;QAElE,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAoE,CAAC;QAE3H,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YACvB,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC;YACtC,KAAK,EAAE,CAAC,CAAC,KAAK;YACd,IAAI,EAAE,CAAC,CAAC,IAAI;SACb,CAAC,CAAC,CAAC;IACN,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,WAAmB,EAAE,UAA2B,EAAE;QAC9D,MAAM,EAAE,OAAO,GAAG,KAAK,EAAE,GAAG,OAAO,CAAC;QACpC,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAE7B,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,GAAG,OAAO,EAAE,CAAC;YACxC,IAAI,CAAC;gBACH,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,GAAG,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;gBAC/E,MAAM,SAAS,GAAG,MAAM,OAAO,CAAC,SAAS,EAAE,CAAC;gBAC5C,IAAI,SAAS,EAAE,CAAC;oBACd,OAAO,OAAO,CAAC;gBACjB,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,0CAA0C;YAC5C,CAAC;YACD,MAAM,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC;QACtC,CAAC;QAED,MAAM,IAAI,KAAK,CAAC,iCAAiC,WAAW,GAAG,CAAC,CAAC;IACnE,CAAC;CACF;AAED,iCAAiC;AACjC,kBAAe,QAAQ,CAAC"}

package/dist/semantic-mapper.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Semantic Mapper - Core classification engine
+ *
+ * Classifies DOM elements by semantic purpose using heuristics,
+ * without requiring LLM calls. Fast, local, privacy-preserving.
+ */
+export type SemanticCategory = 'navigation' | 'action' | 'form' | 'content' | 'data' | 'unknown';
+export interface SemanticElement {
+    selector: string;
+    tagName: string;
+    category: SemanticCategory;
+    confidence: number;
+    textPreview: string | null;
+    role: string | null;
+    ariaLabel: string | null;
+    id: string | null;
+    classes: string | null;
+}
+export interface ClickResult {
+    clicked: boolean;
+    selector?: string;
+    text?: string;
+    score?: number;
+    error?: string;
+}
+export interface QueryResult {
+    selector: string;
+    tagName: string;
+    textPreview: string | null;
+    ariaLabel: string | null;
+}
+/**
+ * Generate JavaScript to analyze page and classify all elements
+ */
+export declare function generateAnalysisScript(includeUnknown?: boolean): string;
+/**
+ * Generate JavaScript to find elements by semantic category
+ */
+export declare function generateQueryScript(category: SemanticCategory, query?: string): string;
+/**
+ * Generate JavaScript to click element by semantic description
+ */
+export declare function generateClickScript(description: string, purposeHint?: SemanticCategory): string;
+/**
+ * Generate JavaScript to fill a form field by semantic description
+ */
+export declare function generateFillScript(description: string, value: string): string;
+//# sourceMappingURL=semantic-mapper.d.ts.map

package/dist/semantic-mapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-mapper.d.ts","sourceRoot":"","sources":["../src/semantic-mapper.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,MAAM,gBAAgB,GAAG,YAAY,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC;AAEjG,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAgBD;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,cAAc,GAAE,OAAe,GAAG,MAAM,CA+J9E;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,gBAAgB,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAwEtF;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,gBAAgB,GAAG,MAAM,CA4F/F;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CA8E7E"}

package/dist/semantic-mapper.js

@@ -0,0 +1,440 @@
+"use strict";
+/**
+ * Semantic Mapper - Core classification engine
+ *
+ * Classifies DOM elements by semantic purpose using heuristics,
+ * without requiring LLM calls. Fast, local, privacy-preserving.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateAnalysisScript = generateAnalysisScript;
+exports.generateQueryScript = generateQueryScript;
+exports.generateClickScript = generateClickScript;
+exports.generateFillScript = generateFillScript;
+/**
+ * Escape string for safe JavaScript injection
+ */
+function escapeJS(str) {
+    return str
+        .replace(/\\/g, '\\\\')
+        .replace(/'/g, "\\'")
+        .replace(/"/g, '\\"')
+        .replace(/`/g, '\\`')
+        .replace(/\$/g, '\\$')
+        .replace(/\n/g, '\\n')
+        .replace(/\r/g, '\\r');
+}
+/**
+ * Generate JavaScript to analyze page and classify all elements
+ */
+function generateAnalysisScript(includeUnknown = false) {
+    return `
+(function() {
+  'use strict';
+
+  // Generate unique CSS selector for element
+  function getUniqueSelector(el) {
+    if (el.id) return '#' + CSS.escape(el.id);
+
+    let path = [];
+    while (el && el.nodeType === Node.ELEMENT_NODE) {
+      let selector = el.tagName.toLowerCase();
+
+      if (el.id) {
+        selector = '#' + CSS.escape(el.id);
+        path.unshift(selector);
+        break;
+      }
+
+      let sibling = el;
+      let nth = 1;
+      while (sibling = sibling.previousElementSibling) {
+        if (sibling.tagName === el.tagName) nth++;
+      }
+
+      if (nth > 1 || el.nextElementSibling?.tagName === el.tagName) {
+        selector += ':nth-of-type(' + nth + ')';
+      }
+
+      path.unshift(selector);
+      el = el.parentElement;
+    }
+
+    return path.join(' > ');
+  }
+
+  // Classify element by semantic purpose
+  function classify(el) {
+    const tag = el.tagName.toLowerCase();
+    const role = el.getAttribute('role');
+    const classes = Array.from(el.classList).join(' ').toLowerCase();
+    const id = (el.id || '').toLowerCase();
+    const type = el.type || '';
+
+    // Navigation patterns
+    if (tag === 'nav' || role === 'navigation' || role === 'menu' || role === 'menubar') {
+      return { category: 'navigation', confidence: 0.95 };
+    }
+    if (classes.match(/\\b(nav|menu|breadcrumb|pagination|sidebar|header-links)\\b/) ||
+        id.match(/\\b(nav|menu|navigation)\\b/)) {
+      return { category: 'navigation', confidence: 0.85 };
+    }
+    if (tag === 'a' && el.closest('nav, [role="navigation"]')) {
+      return { category: 'navigation', confidence: 0.80 };
+    }
+
+    // Action patterns
+    if (tag === 'button' || role === 'button') {
+      return { category: 'action', confidence: 0.95 };
+    }
+    if (type === 'submit' || type === 'button') {
+      return { category: 'action', confidence: 0.90 };
+    }
+    if (classes.match(/\\b(btn|button|cta|action|submit)\\b/)) {
+      return { category: 'action', confidence: 0.85 };
+    }
+    if (tag === 'a' && classes.match(/\\b(btn|button|cta)\\b/)) {
+      return { category: 'action', confidence: 0.85 };
+    }
+
+    // Form patterns
+    if (tag === 'form' || role === 'form') {
+      return { category: 'form', confidence: 0.95 };
+    }
+    if (['input', 'textarea', 'select'].includes(tag)) {
+      return { category: 'form', confidence: 0.95 };
+    }
+    if (role === 'textbox' || role === 'combobox' || role === 'listbox' || role === 'checkbox' || role === 'radio') {
+      return { category: 'form', confidence: 0.90 };
+    }
+    if (classes.match(/\\b(form|input|field|control)\\b/) && tag !== 'button') {
+      return { category: 'form', confidence: 0.75 };
+    }
+
+    // Data patterns
+    if (tag === 'table' || role === 'table' || role === 'grid') {
+      return { category: 'data', confidence: 0.95 };
+    }
+    if (role === 'list' || role === 'listitem') {
+      return { category: 'data', confidence: 0.85 };
+    }
+    if (tag === 'dl' || tag === 'ul' || tag === 'ol') {
+      if (!el.closest('nav, [role="navigation"]')) {
+        return { category: 'data', confidence: 0.70 };
+      }
+    }
+    if (classes.match(/\\b(table|list|grid|card|item|row)\\b/)) {
+      return { category: 'data', confidence: 0.70 };
+    }
+
+    // Content patterns
+    if (tag === 'main' || tag === 'article' || role === 'main' || role === 'article') {
+      return { category: 'content', confidence: 0.95 };
+    }
+    if (['h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'p', 'section'].includes(tag)) {
+      return { category: 'content', confidence: 0.85 };
+    }
+    if (role === 'heading' || role === 'region') {
+      return { category: 'content', confidence: 0.80 };
+    }
+    if (classes.match(/\\b(content|article|post|text|body|main)\\b/)) {
+      return { category: 'content', confidence: 0.75 };
+    }
+
+    return { category: 'unknown', confidence: 0.0 };
+  }
+
+  // Get meaningful elements
+  const elements = [];
+  const meaningfulTags = new Set([
+    'nav', 'main', 'article', 'section', 'aside', 'header', 'footer',
+    'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'p',
+    'a', 'button', 'input', 'select', 'textarea', 'form',
+    'table', 'ul', 'ol', 'dl', 'div'
+  ]);
+
+  const selector = Array.from(meaningfulTags).join(',') + ',[role]';
+
+  document.querySelectorAll(selector).forEach(el => {
+    const style = getComputedStyle(el);
+    if (style.display === 'none' || style.visibility === 'hidden') return;
+
+    const rect = el.getBoundingClientRect();
+    if (rect.width < 10 || rect.height < 10) return;
+
+    const { category, confidence } = classify(el);
+
+    if (category === 'unknown' && !${includeUnknown}) return;
+
+    let textPreview = '';
+    if (el.textContent) {
+      textPreview = el.textContent.trim().replace(/\\s+/g, ' ').substring(0, 100);
+    }
+
+    elements.push({
+      selector: getUniqueSelector(el),
+      tagName: el.tagName.toLowerCase(),
+      category: category,
+      confidence: confidence,
+      textPreview: textPreview || null,
+      role: el.getAttribute('role') || null,
+      ariaLabel: el.getAttribute('aria-label') || null,
+      id: el.id || null,
+      classes: Array.from(el.classList).join(' ') || null
+    });
+  });
+
+  return elements;
+})()`;
+}
+/**
+ * Generate JavaScript to find elements by semantic category
+ */
+function generateQueryScript(category, query) {
+    const queryFilter = query?.toLowerCase() ?? '';
+    return `
+(function() {
+  'use strict';
+
+  const targetCategory = '${category}';
+  const searchQuery = '${escapeJS(queryFilter)}'.toLowerCase();
+
+  function getUniqueSelector(el) {
+    if (el.id) return '#' + CSS.escape(el.id);
+    let path = [];
+    while (el && el.nodeType === Node.ELEMENT_NODE) {
+      let selector = el.tagName.toLowerCase();
+      if (el.id) {
+        selector = '#' + CSS.escape(el.id);
+        path.unshift(selector);
+        break;
+      }
+      let sibling = el;
+      let nth = 1;
+      while (sibling = sibling.previousElementSibling) {
+        if (sibling.tagName === el.tagName) nth++;
+      }
+      if (nth > 1 || el.nextElementSibling?.tagName === el.tagName) {
+        selector += ':nth-of-type(' + nth + ')';
+      }
+      path.unshift(selector);
+      el = el.parentElement;
+    }
+    return path.join(' > ');
+  }
+
+  function classify(el) {
+    const tag = el.tagName.toLowerCase();
+    const role = el.getAttribute('role');
+    const classes = Array.from(el.classList).join(' ').toLowerCase();
+
+    if (tag === 'nav' || role === 'navigation' || classes.match(/\\bnav\\b/)) return 'navigation';
+    if (tag === 'button' || role === 'button' || el.type === 'submit' || classes.match(/\\bbtn\\b/)) return 'action';
+    if (['input', 'textarea', 'select', 'form'].includes(tag) || role === 'textbox') return 'form';
+    if (tag === 'table' || role === 'table' || role === 'list') return 'data';
+    if (['main', 'article', 'h1', 'h2', 'h3', 'p', 'section'].includes(tag) || role === 'main') return 'content';
+    return 'unknown';
+  }
+
+  const matches = [];
+  document.querySelectorAll('*').forEach(el => {
+    const style = getComputedStyle(el);
+    if (style.display === 'none' || style.visibility === 'hidden') return;
+
+    const category = classify(el);
+    if (category !== targetCategory) return;
+
+    const text = el.textContent?.trim().toLowerCase() || '';
+    const ariaLabel = (el.getAttribute('aria-label') || '').toLowerCase();
+
+    if (searchQuery && !text.includes(searchQuery) && !ariaLabel.includes(searchQuery)) {
+      return;
+    }
+
+    matches.push({
+      selector: getUniqueSelector(el),
+      tagName: el.tagName.toLowerCase(),
+      textPreview: el.textContent?.trim().substring(0, 100) || null,
+      ariaLabel: el.getAttribute('aria-label') || null
+    });
+  });
+
+  return matches.slice(0, 50);
+})()`;
+}
+/**
+ * Generate JavaScript to click element by semantic description
+ */
+function generateClickScript(description, purposeHint) {
+    const searchText = description.toLowerCase();
+    const purposeFilter = purposeHint ?? '';
+    return `
+(function() {
+  'use strict';
+
+  const searchText = '${escapeJS(searchText)}'.toLowerCase();
+  const purposeHint = '${purposeFilter}';
+
+  function getUniqueSelector(el) {
+    if (el.id) return '#' + CSS.escape(el.id);
+    let path = [];
+    while (el && el.nodeType === Node.ELEMENT_NODE) {
+      let selector = el.tagName.toLowerCase();
+      if (el.id) { selector = '#' + CSS.escape(el.id); path.unshift(selector); break; }
+      let sibling = el, nth = 1;
+      while (sibling = sibling.previousElementSibling) { if (sibling.tagName === el.tagName) nth++; }
+      if (nth > 1 || el.nextElementSibling?.tagName === el.tagName) selector += ':nth-of-type(' + nth + ')';
+      path.unshift(selector);
+      el = el.parentElement;
+    }
+    return path.join(' > ');
+  }
+
+  function classify(el) {
+    const tag = el.tagName.toLowerCase();
+    const role = el.getAttribute('role');
+    if (tag === 'nav' || role === 'navigation') return 'navigation';
+    if (tag === 'button' || role === 'button' || el.type === 'submit') return 'action';
+    if (['input', 'textarea', 'select', 'form'].includes(tag)) return 'form';
+    if (tag === 'table' || role === 'table') return 'data';
+    if (['main', 'article', 'h1', 'p'].includes(tag)) return 'content';
+    return 'unknown';
+  }
+
+  function scoreMatch(el) {
+    const text = (el.textContent || '').toLowerCase();
+    const ariaLabel = (el.getAttribute('aria-label') || '').toLowerCase();
+    const title = (el.getAttribute('title') || '').toLowerCase();
+    const id = (el.id || '').toLowerCase();
+    const classes = Array.from(el.classList).join(' ').toLowerCase();
+
+    let score = 0;
+
+    // Exact matches score highest
+    if (text.trim() === searchText || ariaLabel === searchText) score += 100;
+    else if (text.includes(searchText) || ariaLabel.includes(searchText)) score += 50;
+    if (title.includes(searchText)) score += 30;
+    if (id.includes(searchText.replace(/\\s+/g, '-'))) score += 25;
+    if (classes.includes(searchText.replace(/\\s+/g, '-'))) score += 20;
+
+    // Purpose match bonus
+    if (purposeHint && classify(el) === purposeHint) score += 40;
+
+    // Prefer buttons for action-like queries
+    if (searchText.match(/button|submit|click|press/) && (el.tagName === 'BUTTON' || el.type === 'submit')) {
+      score += 30;
+    }
+
+    return score;
+  }
+
+  const clickables = document.querySelectorAll('a, button, [role="button"], input[type="submit"], [onclick]');
+
+  let bestMatch = null;
+  let bestScore = 0;
+
+  clickables.forEach(el => {
+    const style = getComputedStyle(el);
+    if (style.display === 'none' || style.visibility === 'hidden') return;
+
+    const score = scoreMatch(el);
+    if (score > bestScore) {
+      bestScore = score;
+      bestMatch = el;
+    }
+  });
+
+  if (bestMatch && bestScore >= 20) {
+    bestMatch.click();
+    return {
+      clicked: true,
+      selector: getUniqueSelector(bestMatch),
+      text: bestMatch.textContent?.trim().substring(0, 100) || null,
+      score: bestScore
+    };
+  }
+
+  return { clicked: false, error: 'No matching element found' };
+})()`;
+}
+/**
+ * Generate JavaScript to fill a form field by semantic description
+ */
+function generateFillScript(description, value) {
+    const searchText = description.toLowerCase();
+    const escapedValue = escapeJS(value);
+    return `
+(function() {
+  'use strict';
+
+  const searchText = '${escapeJS(searchText)}'.toLowerCase();
+  const fillValue = '${escapedValue}';
+
+  function getUniqueSelector(el) {
+    if (el.id) return '#' + CSS.escape(el.id);
+    let path = [];
+    while (el && el.nodeType === Node.ELEMENT_NODE) {
+      let selector = el.tagName.toLowerCase();
+      if (el.id) { selector = '#' + CSS.escape(el.id); path.unshift(selector); break; }
+      let sibling = el, nth = 1;
+      while (sibling = sibling.previousElementSibling) { if (sibling.tagName === el.tagName) nth++; }
+      if (nth > 1 || el.nextElementSibling?.tagName === el.tagName) selector += ':nth-of-type(' + nth + ')';
+      path.unshift(selector);
+      el = el.parentElement;
+    }
+    return path.join(' > ');
+  }
+
+  function scoreMatch(el) {
+    const tag = el.tagName.toLowerCase();
+    if (!['input', 'textarea', 'select'].includes(tag)) return 0;
+
+    const label = document.querySelector('label[for="' + el.id + '"]');
+    const labelText = label ? label.textContent.toLowerCase() : '';
+    const placeholder = (el.placeholder || '').toLowerCase();
+    const name = (el.name || '').toLowerCase();
+    const ariaLabel = (el.getAttribute('aria-label') || '').toLowerCase();
+    const id = (el.id || '').toLowerCase();
+
+    let score = 0;
+
+    if (labelText.includes(searchText)) score += 100;
+    if (ariaLabel.includes(searchText)) score += 90;
+    if (placeholder.includes(searchText)) score += 80;
+    if (name.includes(searchText.replace(/\\s+/g, '_'))) score += 70;
+    if (id.includes(searchText.replace(/\\s+/g, '-'))) score += 60;
+
+    return score;
+  }
+
+  const inputs = document.querySelectorAll('input, textarea, select');
+
+  let bestMatch = null;
+  let bestScore = 0;
+
+  inputs.forEach(el => {
+    const style = getComputedStyle(el);
+    if (style.display === 'none' || style.visibility === 'hidden') return;
+    if (el.disabled || el.readOnly) return;
+
+    const score = scoreMatch(el);
+    if (score > bestScore) {
+      bestScore = score;
+      bestMatch = el;
+    }
+  });
+
+  if (bestMatch && bestScore >= 50) {
+    bestMatch.value = fillValue;
+    bestMatch.dispatchEvent(new Event('input', { bubbles: true }));
+    bestMatch.dispatchEvent(new Event('change', { bubbles: true }));
+    return {
+      filled: true,
+      selector: getUniqueSelector(bestMatch),
+      score: bestScore
+    };
+  }
+
+  return { filled: false, error: 'No matching input found' };
+})()`;
+}
+//# sourceMappingURL=semantic-mapper.js.map

package/dist/semantic-mapper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-mapper.js","sourceRoot":"","sources":["../src/semantic-mapper.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;AAgDH,wDA+JC;AAKD,kDAwEC;AAKD,kDA4FC;AAKD,gDA8EC;AAjbD;;GAEG;AACH,SAAS,QAAQ,CAAC,GAAW;IAC3B,OAAO,GAAG;SACP,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC;SACtB,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC;SACpB,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC;SACpB,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC;SACpB,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC;SACrB,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC;SACrB,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;AAC3B,CAAC;AAED;;GAEG;AACH,SAAgB,sBAAsB,CAAC,iBAA0B,KAAK;IACpE,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qCAwI4B,cAAc;;;;;;;;;;;;;;;;;;;;;KAqB9C,CAAC;AACN,CAAC;AAED;;GAEG;AACH,SAAgB,mBAAmB,CAAC,QAA0B,EAAE,KAAc;IAC5E,MAAM,WAAW,GAAG,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;IAE/C,OAAO;;;;4BAImB,QAAQ;yBACX,QAAQ,CAAC,WAAW,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KA+DzC,CAAC;AACN,CAAC;AAED;;GAEG;AACH,SAAgB,mBAAmB,CAAC,WAAmB,EAAE,WAA8B;IACrF,MAAM,UAAU,GAAG,WAAW,CAAC,WAAW,EAAE,CAAC;IAC7C,MAAM,aAAa,GAAG,WAAW,IAAI,EAAE,CAAC;IAExC,OAAO;;;;wBAIe,QAAQ,CAAC,UAAU,CAAC;yBACnB,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAkFjC,CAAC;AACN,CAAC;AAED;;GAEG;AACH,SAAgB,kBAAkB,CAAC,WAAmB,EAAE,KAAa;IACnE,MAAM,UAAU,GAAG,WAAW,CAAC,WAAW,EAAE,CAAC;IAC7C,MAAM,YAAY,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAErC,OAAO;;;;wBAIe,QAAQ,CAAC,UAAU,CAAC;uBACrB,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAoE9B,CAAC;AACN,CAAC"}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "semantic-playwright",
+  "version": "0.1.0",
+  "description": "Semantic element targeting for Playwright - click by description, not selectors",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "playwright test",
+    "lint": "eslint src --ext .ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "playwright",
+    "testing",
+    "automation",
+    "semantic",
+    "self-healing",
+    "web-automation",
+    "e2e",
+    "locators"
+  ],
+  "author": "",
+  "license": "MIT",
+  "peerDependencies": {
+    "@playwright/test": ">=1.40.0",
+    "playwright": ">=1.40.0"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.40.0",
+    "@types/node": "^20.10.0",
+    "typescript": "^5.3.0"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/semantic-engine/semantic-playwright"
+  }
+}