playwright-genie 1.0.0

package/dist/index.cjs

@@ -0,0 +1,1185 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/entry.js
+var entry_exports = {};
+__export(entry_exports, {
+  SmartAction: () => SmartAction,
+  chatCompletion: () => chatCompletion,
+  clearAllCaches: () => clearAllCaches,
+  clearCache: () => clearCache,
+  createSmartLocator: () => createSmartLocator,
+  findAllMatches: () => findAllMatches,
+  findLocator: () => findLocator,
+  getConfig: () => getConfig,
+  getLocator: () => getLocator,
+  getPageStructure: () => getPageStructure,
+  resolveLocator: () => resolveLocator,
+  resolveLocatorsBatch: () => resolveLocatorsBatch
+});
+module.exports = __toCommonJS(entry_exports);
+
+// src/llm/client.js
+var import_config = require("dotenv/config");
+var import_openai = __toESM(require("openai"), 1);
+var DEBUG = process.env.LLM_LOCATOR_DEBUG === "true";
+var LLM_API_KEY = process.env.LLM_API_KEY || process.env.ROUTELLM_API_KEY || process.env.OPENAI_API_KEY || process.env.ANTHROPIC_API_KEY;
+var LLM_BASE_URL = process.env.LLM_BASE_URL || process.env.ROUTELLM_BASE_URL || "https://api.openai.com/v1";
+var LLM_MODEL = process.env.LLM_MODEL || process.env.ROUTELLM_MODEL || "gpt-4o-mini";
+if (!LLM_API_KEY) {
+  throw new Error(
+    "No LLM API key found. Set one of: LLM_API_KEY, ROUTELLM_API_KEY, OPENAI_API_KEY, or ANTHROPIC_API_KEY"
+  );
+}
+var client = new import_openai.default({
+  baseURL: LLM_BASE_URL,
+  apiKey: LLM_API_KEY
+});
+async function chatCompletion(messages, options = {}) {
+  const {
+    model = LLM_MODEL,
+    temperature = 0,
+    maxTokens = 1024
+  } = options;
+  if (DEBUG) {
+    console.log(`[LLM Client] model=${model} base=${LLM_BASE_URL} msgs=${messages.length}`);
+  }
+  const completion = await client.chat.completions.create({
+    model,
+    temperature,
+    max_tokens: maxTokens,
+    messages
+  });
+  return completion.choices[0].message.content.trim();
+}
+function getConfig() {
+  return {
+    apiKey: LLM_API_KEY ? "***" + LLM_API_KEY.slice(-4) : null,
+    baseUrl: LLM_BASE_URL,
+    model: LLM_MODEL
+  };
+}
+
+// src/llm/prompt.js
+var SYSTEM_PROMPT = `You are an expert at generating Playwright locators from page structure.
+You receive a (possibly trimmed) accessibility tree in YAML and special DOM elements.
+
+CRITICAL RULES:
+1. ONLY use exact text/names that EXIST in the provided structure. NEVER invent or echo the user's query as locator text.
+2. The user's query is a DESCRIPTION of the element, NOT the element's text. You must FIND the matching element in the tree.
+   Example: Query "Admin Tab" \u2192 find the link/tab named "Admin" in the tree \u2192 getByRole('link', { name: /Admin/i })
+   Example: Query "login button" \u2192 find button named "Login" in the tree \u2192 getByRole('button', { name: /Login/i })
+3. YAML format: "- link \\"Sign in\\"" means a link element with accessible name "Sign in"
+   "- textbox \\"Username\\"" means a textbox with accessible name "Username"
+4. Prefer getByRole with name regex: { name: /text/i } for robustness.
+5. Words like "tab", "button", "link", "field", "textbox", "input" in the query describe the ELEMENT TYPE, not the text content.
+
+ACTION-AWARE RULES:
+- If action is "fill", "type", "clear", "press": The target MUST be an editable element (textbox, searchbox, combobox, input). Use getByRole('textbox', ...) or getByPlaceholder or getByLabel. NEVER target a label or static text.
+- If action is "click", "dblclick", "tap", "focus", "hover": Target the interactive element (link, button, tab, menuitem, etc).
+- If action is "check", "uncheck": Target a checkbox or radio element.
+- If action is "select": Target a combobox or listbox element.
+- If action is "getText" or null: Target any matching element.
+
+PRIORITY: getByTestId > getByRole > getByLabel > getByPlaceholder > getByAltText > getByTitle > getByText > locator(CSS)
+For iframes: page.frameLocator('sel').getByRole(...)
+For positional: .first() / .nth(n) / .last()
+
+Return ONLY valid JSON.`;
+function buildMessages(payloadStr, query, action) {
+  const actionHint = action ? `
+Action: "${action}" (the locator MUST target an element appropriate for this action)` : "";
+  return [
+    { role: "system", content: SYSTEM_PROMPT },
+    {
+      role: "user",
+      content: `Page:
+${payloadStr}
+
+Find element described as: "${query}"${actionHint}
+
+IMPORTANT: Match the query to an ACTUAL element in the tree above. Do NOT use the query text as locator text.
+
+JSON: { "strategy":"\u2026", "locatorString":"page.getBy\u2026()", "isInFrame":false, "frameSelector":null, "confidence":0.95, "reasoning":"\u2026" }`
+    }
+  ];
+}
+function buildBatchMessages(payloadStr, queries) {
+  const queriesList = queries.map((q, i) => `${i + 1}. "${q}"`).join("\n");
+  return [
+    { role: "system", content: SYSTEM_PROMPT },
+    {
+      role: "user",
+      content: `Page:
+${payloadStr}
+
+Find locators for ALL (match each query to ACTUAL elements in the tree, do NOT echo query text):
+${queriesList}
+
+Return JSON array:
+[{ "query":"\u2026", "strategy":"\u2026", "locatorString":"page.getBy\u2026()", "isInFrame":false, "frameSelector":null, "confidence":0.95, "reasoning":"\u2026" }]`
+    }
+  ];
+}
+
+// src/llm/parser.js
+function parseJsonResponse(raw) {
+  let text = raw.trim();
+  if (text.startsWith("```")) {
+    text = text.replace(/```json?\n?/g, "").replace(/```\n?$/g, "");
+  }
+  return JSON.parse(text);
+}
+function createPlaywrightLocator(page, locatorString, isInFrame, frameSelector) {
+  let code = locatorString.replace(/^page\./, "");
+  let context = page;
+  if (isInFrame && frameSelector) {
+    context = page.frameLocator(frameSelector);
+    code = code.replace(/^frameLocator\([^)]+\)\./, "");
+  }
+  return evalLocator(context, code);
+}
+function parseInlineOptions(str) {
+  if (!str) return {};
+  const opts = {};
+  const nameRegex = str.match(/name:\s*\/([^/]+)\/([gimsuy]*)/);
+  const nameStr = str.match(/name:\s*'([^']+)'/);
+  const exact = str.match(/exact:\s*(true|false)/);
+  if (nameRegex) opts.name = new RegExp(nameRegex[1], nameRegex[2] || void 0);
+  else if (nameStr) opts.name = nameStr[1];
+  if (exact) opts.exact = exact[1] === "true";
+  return opts;
+}
+function parseTextArg(quoted, regexBody, regexFlags) {
+  if (quoted) return quoted;
+  if (regexBody) return new RegExp(regexBody, regexFlags || void 0);
+  return null;
+}
+function parseFilterOptions(str) {
+  if (!str) return {};
+  const opts = {};
+  const hasText = str.match(/hasText:\s*(?:'([^']+)'|\/([^/]+)\/([gimsuy]*))/);
+  const hasNotText = str.match(/hasNotText:\s*(?:'([^']+)'|\/([^/]+)\/([gimsuy]*))/);
+  if (hasText) opts.hasText = hasText[1] || new RegExp(hasText[2], hasText[3] || void 0);
+  if (hasNotText) opts.hasNotText = hasNotText[1] || new RegExp(hasNotText[2], hasNotText[3] || void 0);
+  return opts;
+}
+function evalLocator(context, code) {
+  const patterns = [
+    {
+      regex: /getByRole\('([^']+)'(?:,\s*({[^}]+}))?\)(.*)/,
+      handler: (m) => {
+        const opts = parseInlineOptions(m[2]);
+        return applyChain(context.getByRole(m[1], opts), m[3]);
+      }
+    },
+    {
+      regex: /getByTestId\('([^']+)'\)(.*)/,
+      handler: (m) => applyChain(context.getByTestId(m[1]), m[2])
+    },
+    {
+      regex: /getByLabel\((?:'([^']+)'|\/([^/]+)\/([gimsuy]*))(?:,\s*({[^}]+}))?\)(.*)/,
+      handler: (m) => {
+        const t = parseTextArg(m[1], m[2], m[3]);
+        const opts = parseInlineOptions(m[4]);
+        return applyChain(context.getByLabel(t, opts), m[5]);
+      }
+    },
+    {
+      regex: /getByPlaceholder\((?:'([^']+)'|\/([^/]+)\/([gimsuy]*))(?:,\s*({[^}]+}))?\)(.*)/,
+      handler: (m) => {
+        const t = parseTextArg(m[1], m[2], m[3]);
+        const opts = parseInlineOptions(m[4]);
+        return applyChain(context.getByPlaceholder(t, opts), m[5]);
+      }
+    },
+    {
+      regex: /getByText\((?:'([^']+)'|\/([^/]+)\/([gimsuy]*))(?:,\s*({[^}]+}))?\)(.*)/,
+      handler: (m) => {
+        const t = parseTextArg(m[1], m[2], m[3]);
+        const opts = parseInlineOptions(m[4]);
+        return applyChain(context.getByText(t, opts), m[5]);
+      }
+    },
+    {
+      regex: /getByAltText\((?:'([^']+)'|\/([^/]+)\/([gimsuy]*))(?:,\s*({[^}]+}))?\)(.*)/,
+      handler: (m) => {
+        const t = parseTextArg(m[1], m[2], m[3]);
+        const opts = parseInlineOptions(m[4]);
+        return applyChain(context.getByAltText(t, opts), m[5]);
+      }
+    },
+    {
+      regex: /getByTitle\((?:'([^']+)'|\/([^/]+)\/([gimsuy]*))(?:,\s*({[^}]+}))?\)(.*)/,
+      handler: (m) => {
+        const t = parseTextArg(m[1], m[2], m[3]);
+        const opts = parseInlineOptions(m[4]);
+        return applyChain(context.getByTitle(t, opts), m[5]);
+      }
+    },
+    {
+      regex: /locator\('([^']+)'\)(.*)/,
+      handler: (m) => applyChain(context.locator(m[1]), m[2])
+    }
+  ];
+  for (const p of patterns) {
+    const match = code.match(p.regex);
+    if (match) return p.handler(match);
+  }
+  throw new Error(`Unsupported locator pattern: ${code}`);
+}
+function applyChain(loc, chain) {
+  if (!chain?.trim()) return loc;
+  if (chain.includes(".first()")) {
+    loc = loc.first();
+    chain = chain.replace(".first()", "");
+  }
+  if (chain.includes(".last()")) {
+    loc = loc.last();
+    chain = chain.replace(".last()", "");
+  }
+  const n = chain.match(/\.nth\((\d+)\)/);
+  if (n) loc = loc.nth(parseInt(n[1]));
+  const f = chain.match(/\.filter\(({[^}]+})\)/);
+  if (f) loc = loc.filter(parseFilterOptions(f[1]));
+  return loc;
+}
+async function validateLocator(locator, timeoutMs = 3e3) {
+  try {
+    await locator.waitFor({ state: "attached", timeout: timeoutMs });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/cache/disk-cache.js
+var import_fs = __toESM(require("fs"), 1);
+var import_path = __toESM(require("path"), 1);
+var DEBUG2 = process.env.LLM_LOCATOR_DEBUG === "true";
+var CACHE_FILE = process.env.LOCATOR_CACHE_FILE || ".locator-cache.json";
+var diskCache = null;
+function loadDiskCache() {
+  if (diskCache !== null) return diskCache;
+  const filePath = import_path.default.resolve(CACHE_FILE);
+  try {
+    if (import_fs.default.existsSync(filePath)) {
+      diskCache = JSON.parse(import_fs.default.readFileSync(filePath, "utf-8"));
+      if (DEBUG2) console.log(`[Disk Cache] Loaded ${Object.keys(diskCache).length} entries from ${CACHE_FILE}`);
+    } else {
+      diskCache = {};
+    }
+  } catch (e) {
+    console.warn(`[Disk Cache] Failed to read ${CACHE_FILE}:`, e.message);
+    diskCache = {};
+  }
+  return diskCache;
+}
+function saveDiskCache() {
+  const filePath = import_path.default.resolve(CACHE_FILE);
+  try {
+    import_fs.default.writeFileSync(filePath, JSON.stringify(diskCache, null, 2), "utf-8");
+  } catch (e) {
+    console.warn(`[Disk Cache] Failed to write ${CACHE_FILE}:`, e.message);
+  }
+}
+function makeCacheKey(urlOrPage, query, action) {
+  let urlPath;
+  if (typeof urlOrPage === "string") {
+    try {
+      urlPath = new URL(urlOrPage).pathname;
+    } catch {
+      urlPath = urlOrPage;
+    }
+  } else {
+    try {
+      urlPath = new URL(urlOrPage.url()).pathname;
+    } catch {
+      urlPath = urlOrPage.url();
+    }
+  }
+  return `${urlPath}::${(action || "any").toLowerCase()}::${query.toLowerCase().trim()}`;
+}
+function getDiskEntry(url, query, action) {
+  const cache = loadDiskCache();
+  return cache[makeCacheKey(url, query, action)] || null;
+}
+function setDiskEntry(url, query, action, entry) {
+  const cache = loadDiskCache();
+  cache[makeCacheKey(url, query, action)] = {
+    locatorString: entry.locatorString,
+    strategy: entry.strategy,
+    isInFrame: entry.isInFrame || false,
+    frameSelector: entry.frameSelector || null,
+    confidence: entry.confidence,
+    reasoning: entry.reasoning,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    hitCount: 0
+  };
+  saveDiskCache();
+}
+function invalidateDiskEntry(url, query, action) {
+  const cache = loadDiskCache();
+  const key = makeCacheKey(url, query, action);
+  if (cache[key]) {
+    delete cache[key];
+    saveDiskCache();
+    return true;
+  }
+  return false;
+}
+function bumpHitCount(url, query, action) {
+  const cache = loadDiskCache();
+  const key = makeCacheKey(url, query, action);
+  if (cache[key]) {
+    cache[key].hitCount = (cache[key].hitCount || 0) + 1;
+    cache[key].lastUsed = (/* @__PURE__ */ new Date()).toISOString();
+    saveDiskCache();
+  }
+}
+function clearDiskCache() {
+  diskCache = {};
+  saveDiskCache();
+}
+
+// src/cache/memory-cache.js
+var memCache = /* @__PURE__ */ new Map();
+var structureCache = { url: null, timestamp: 0, data: null };
+var STRUCTURE_TTL = 8e3;
+function getMemKey(url, query, action) {
+  return `${url}::${(action || "any").toLowerCase()}::${query.toLowerCase().trim()}`;
+}
+function getMemEntry(url, query, action) {
+  return memCache.get(getMemKey(url, query, action)) || null;
+}
+function setMemEntry(url, query, action, entry) {
+  memCache.set(getMemKey(url, query, action), entry);
+}
+function deleteMemEntry(url, query, action) {
+  memCache.delete(getMemKey(url, query, action));
+}
+function getStructureCache() {
+  return structureCache;
+}
+function setStructureCache(url, data) {
+  structureCache = { url, timestamp: Date.now(), data };
+}
+function isStructureCacheValid(url) {
+  return structureCache.url === url && Date.now() - structureCache.timestamp < STRUCTURE_TTL && structureCache.data;
+}
+function clearStructureCache() {
+  structureCache = { url: null, timestamp: 0, data: null };
+}
+function clearMemoryCache() {
+  memCache.clear();
+  clearStructureCache();
+}
+
+// src/page-structure.js
+var DEBUG3 = process.env.LLM_LOCATOR_DEBUG === "true";
+async function getPageStructure(page, forceRefresh = false) {
+  const url = page.url();
+  if (!forceRefresh && isStructureCacheValid(url)) {
+    if (DEBUG3) console.log("[Page Structure] Using cached");
+    return getStructureCache().data;
+  }
+  const structure = { mainFrame: await getFrameStructure(page), frames: [] };
+  for (const frame of page.frames()) {
+    if (frame === page.mainFrame()) continue;
+    try {
+      const frameElement = await frame.frameElement();
+      const frameInfo = await page.evaluate((el) => ({
+        id: el.id || null,
+        name: el.name || null,
+        selector: el.id ? `#${el.id}` : el.name ? `iframe[name="${el.name}"]` : el.title ? `iframe[title="${el.title}"]` : "iframe"
+      }), frameElement);
+      structure.frames.push({ ...frameInfo, content: await getFrameStructure(frame) });
+    } catch (e) {
+    }
+  }
+  setStructureCache(url, structure);
+  return structure;
+}
+async function getFrameStructure(pageOrFrame) {
+  let ariaTree = null;
+  let specialElements = [];
+  const [ariaResult, domResult] = await Promise.allSettled([
+    pageOrFrame.locator("body").ariaSnapshot({ timeout: 5e3 }),
+    pageOrFrame.evaluate(() => {
+      const els = [];
+      for (const el of document.querySelectorAll(
+        "[data-testid], [data-test-id], [data-test], [data-qa], [data-cy], [placeholder], [alt], [aria-label]"
+      )) {
+        const e = {
+          tag: el.tagName.toLowerCase(),
+          testId: el.getAttribute("data-testid") || el.getAttribute("data-test-id") || el.getAttribute("data-test") || el.getAttribute("data-qa") || el.getAttribute("data-cy") || null,
+          placeholder: el.getAttribute("placeholder") || null,
+          alt: el.getAttribute("alt") || null,
+          ariaLabel: el.getAttribute("aria-label") || null
+        };
+        if (e.testId || e.placeholder || e.alt || e.ariaLabel) els.push(e);
+      }
+      return els;
+    })
+  ]);
+  if (ariaResult.status === "fulfilled") ariaTree = ariaResult.value;
+  else {
+    try {
+      if (typeof pageOrFrame.mainFrame === "function") {
+        const snap = await pageOrFrame.accessibility.snapshot();
+        if (snap) ariaTree = JSON.stringify(simplifyAriaTree(snap));
+      }
+    } catch (e) {
+    }
+  }
+  if (domResult.status === "fulfilled") specialElements = domResult.value;
+  return { ariaTree, specialElements };
+}
+function simplifyAriaTree(node, depth = 0) {
+  if (!node || depth > 8) return null;
+  const s = {};
+  if (node.role) s.role = node.role;
+  if (node.name) s.name = node.name;
+  if (node.children?.length) {
+    s.children = node.children.map((c) => simplifyAriaTree(c, depth + 1)).filter(Boolean);
+  }
+  return s;
+}
+function trimSnapshotForQuery(ariaYaml, query, maxLines = 150) {
+  if (!ariaYaml || typeof ariaYaml !== "string") return ariaYaml;
+  const lines = ariaYaml.split("\n");
+  if (lines.length <= maxLines) return ariaYaml;
+  const queryTokens = query.toLowerCase().replace(/[^a-z0-9\s]/g, "").split(/\s+/).filter(Boolean);
+  const scoredLines = lines.map((line, idx) => {
+    const lower = line.toLowerCase();
+    let score = 0;
+    for (const token of queryTokens) {
+      if (lower.includes(token)) score += 10;
+    }
+    if (/button|link|textbox|searchbox|combobox|checkbox|tab\b/.test(lower)) score += 3;
+    if (/heading|navigation|banner|main|form/.test(lower)) score += 2;
+    return { line, idx, score };
+  });
+  const relevant = /* @__PURE__ */ new Set();
+  for (const { idx, score } of scoredLines) {
+    if (score > 0) {
+      const contextStart = Math.max(0, idx - 3);
+      const contextEnd = Math.min(lines.length - 1, idx + 2);
+      for (let i = contextStart; i <= contextEnd; i++) relevant.add(i);
+    }
+  }
+  for (let i = 0; i < Math.min(15, lines.length); i++) relevant.add(i);
+  if (relevant.size < maxLines) {
+    const interactive = scoredLines.filter((s) => s.score >= 3 && !relevant.has(s.idx)).sort((a, b) => b.score - a.score);
+    for (const { idx } of interactive) {
+      if (relevant.size >= maxLines) break;
+      relevant.add(idx);
+      if (idx > 0) relevant.add(idx - 1);
+    }
+  }
+  const sorted = [...relevant].sort((a, b) => a - b);
+  const result = [];
+  let lastIdx = -1;
+  for (const idx of sorted) {
+    if (lastIdx !== -1 && idx - lastIdx > 1) result.push("  ...");
+    result.push(lines[idx]);
+    lastIdx = idx;
+  }
+  return result.join("\n");
+}
+
+// src/resolver.js
+var DEBUG4 = process.env.LLM_LOCATOR_DEBUG === "true";
+function buildPayload(pageStructure, query) {
+  const trimmedAria = trimSnapshotForQuery(pageStructure.mainFrame.ariaTree, query);
+  const payload = {
+    ariaTree: trimmedAria,
+    specialElements: pageStructure.mainFrame.specialElements,
+    frames: pageStructure.frames.length > 0 ? pageStructure.frames.map((f) => ({
+      selector: f.selector,
+      ariaTree: trimSnapshotForQuery(f.content?.ariaTree, query, 50),
+      specialElements: f.content?.specialElements || []
+    })) : void 0
+  };
+  let payloadStr = JSON.stringify(payload, null, 2);
+  if (payloadStr.length > 15e3) payloadStr = payloadStr.substring(0, 15e3) + "\n...(truncated)";
+  return payloadStr;
+}
+async function queryLLM(pageStructure, query, options = {}) {
+  const { action = null } = options;
+  const payloadStr = buildPayload(pageStructure, query);
+  if (DEBUG4) console.log("[Resolver] Payload size:", payloadStr.length, "chars");
+  const messages = buildMessages(payloadStr, query, action);
+  const raw = await chatCompletion(messages, options);
+  return parseJsonResponse(raw);
+}
+async function resolveLocator(page, query, options = {}) {
+  const shouldDebug = DEBUG4 || options.debug;
+  const action = options.action || null;
+  const url = page.url();
+  const memHit = getMemEntry(url, query, action);
+  if (memHit) {
+    if (shouldDebug) console.log(`[Memory Cache Hit] "${query}" \u2192 ${memHit.locatorString}`);
+    return memHit;
+  }
+  const diskHit = getDiskEntry(url, query, action);
+  if (diskHit) {
+    if (shouldDebug) console.log(`[Disk Cache Hit] "${query}" \u2192 ${diskHit.locatorString} (hits: ${diskHit.hitCount || 0})`);
+    const result = {
+      found: true,
+      strategy: diskHit.strategy,
+      locatorString: diskHit.locatorString,
+      isInFrame: diskHit.isInFrame || false,
+      frameSelector: diskHit.frameSelector || null,
+      confidence: diskHit.confidence,
+      reasoning: diskHit.reasoning,
+      source: "disk"
+    };
+    setMemEntry(url, query, action, result);
+    return result;
+  }
+  if (shouldDebug) console.log(`[LLM] Querying: "${query}" (action: ${action || "any"})`);
+  const t0 = Date.now();
+  const pageStructure = await getPageStructure(page);
+  try {
+    const parsed = await queryLLM(pageStructure, query, options);
+    const result = {
+      found: parsed.confidence > 0.5,
+      strategy: parsed.strategy,
+      locatorString: parsed.locatorString,
+      isInFrame: parsed.isInFrame || false,
+      frameSelector: parsed.frameSelector || null,
+      confidence: parsed.confidence,
+      reasoning: parsed.reasoning,
+      fallbackLocators: parsed.fallbackLocators || [],
+      source: "llm"
+    };
+    if (shouldDebug) console.log(`[LLM] "${query}" \u2192 ${result.locatorString} (${Date.now() - t0}ms)`);
+    if (result.found) {
+      setMemEntry(url, query, action, result);
+      setDiskEntry(url, query, action, result);
+    }
+    return result;
+  } catch (error) {
+    console.error("LLM locator error:", error.message);
+    return { found: false, confidence: 0, error: error.message, source: "llm" };
+  }
+}
+async function getLocator(page, query, options = {}) {
+  const shouldDebug = DEBUG4 || options.debug;
+  const action = options.action || null;
+  const url = page.url();
+  const result = await resolveLocator(page, query, options);
+  if (!result.found) throw new Error(`Could not find element: ${query}. ${result.error || ""}`);
+  const locator = createPlaywrightLocator(page, result.locatorString, result.isInFrame, result.frameSelector);
+  if (result.source === "disk") {
+    const valid = await validateLocator(locator);
+    if (valid) {
+      bumpHitCount(url, query, action);
+      return { locator, result };
+    }
+    if (shouldDebug) console.log(`[Stale Cache] "${query}" \u2192 ${result.locatorString} no longer valid, re-querying LLM...`);
+    invalidateDiskEntry(url, query, action);
+    deleteMemEntry(url, query, action);
+    clearStructureCache();
+    const freshResult = await resolveLocator(page, query, options);
+    if (!freshResult.found) throw new Error(`Could not find element after retry: ${query}. ${freshResult.error || ""}`);
+    const freshLocator = createPlaywrightLocator(page, freshResult.locatorString, freshResult.isInFrame, freshResult.frameSelector);
+    return { locator: freshLocator, result: freshResult };
+  }
+  return { locator, result };
+}
+async function resolveLocatorsBatch(page, queries, options = {}) {
+  const shouldDebug = DEBUG4 || options.debug;
+  const url = page.url();
+  const results = /* @__PURE__ */ new Map();
+  const uncached = [];
+  for (const q of queries) {
+    const memHit = getMemEntry(url, q, null);
+    if (memHit) {
+      results.set(q, memHit);
+      continue;
+    }
+    const diskHit = getDiskEntry(url, q, null);
+    if (diskHit) {
+      const r = {
+        found: true,
+        strategy: diskHit.strategy,
+        locatorString: diskHit.locatorString,
+        isInFrame: diskHit.isInFrame || false,
+        frameSelector: diskHit.frameSelector || null,
+        confidence: diskHit.confidence,
+        reasoning: diskHit.reasoning,
+        source: "disk"
+      };
+      setMemEntry(url, q, null, r);
+      results.set(q, r);
+    } else {
+      uncached.push(q);
+    }
+  }
+  if (uncached.length === 0) return results;
+  if (shouldDebug) console.log(`[Batch] Resolving ${uncached.length} queries in 1 call`);
+  const t0 = Date.now();
+  const pageStructure = await getPageStructure(page);
+  let payloadStr = buildPayload(pageStructure, uncached.join(" "));
+  if (payloadStr.length > 2e4) payloadStr = payloadStr.substring(0, 2e4) + "\n...(truncated)";
+  try {
+    const messages = buildBatchMessages(payloadStr, uncached);
+    const raw = await chatCompletion(messages, options);
+    const parsed = parseJsonResponse(raw);
+    if (shouldDebug) console.log(`[Batch] ${parsed.length} results in ${Date.now() - t0}ms`);
+    for (let i = 0; i < uncached.length && i < parsed.length; i++) {
+      const p = parsed[i];
+      const result = {
+        found: p.confidence > 0.5,
+        strategy: p.strategy,
+        locatorString: p.locatorString,
+        isInFrame: p.isInFrame || false,
+        frameSelector: p.frameSelector || null,
+        confidence: p.confidence,
+        reasoning: p.reasoning,
+        source: "llm"
+      };
+      results.set(uncached[i], result);
+      if (result.found) {
+        setMemEntry(url, uncached[i], null, result);
+        setDiskEntry(url, uncached[i], null, result);
+      }
+    }
+  } catch (error) {
+    console.error("Batch LLM error:", error.message);
+    for (const q of uncached) {
+      if (!results.has(q)) results.set(q, { found: false, confidence: 0, error: error.message });
+    }
+  }
+  return results;
+}
+
+// src/actions.js
+var DEBUG5 = process.env.LLM_LOCATOR_DEBUG === "true";
+var SmartAction = class _SmartAction {
+  #locator;
+  #result;
+  #query;
+  constructor(locator, result, query) {
+    this.#locator = locator;
+    this.#result = result;
+    this.#query = query;
+  }
+  get rawLocator() {
+    return this.#locator;
+  }
+  get result() {
+    return this.#result;
+  }
+  get query() {
+    return this.#query;
+  }
+  async click(options) {
+    return this.#locator.click(options);
+  }
+  async dblclick(options) {
+    return this.#locator.dblclick(options);
+  }
+  async tap(options) {
+    return this.#locator.tap(options);
+  }
+  async hover(options) {
+    return this.#locator.hover(options);
+  }
+  async focus() {
+    return this.#locator.focus();
+  }
+  async blur() {
+    return this.#locator.blur();
+  }
+  async fill(value, options) {
+    return this.#locator.fill(value, options);
+  }
+  async type(text, options) {
+    return this.#locator.type(text, options);
+  }
+  async press(key, options) {
+    return this.#locator.press(key, options);
+  }
+  async pressSequentially(text, options) {
+    return this.#locator.pressSequentially(text, options);
+  }
+  async clear(options) {
+    return this.#locator.clear(options);
+  }
+  async setInputFiles(files, options) {
+    return this.#locator.setInputFiles(files, options);
+  }
+  async selectOption(values, options) {
+    return this.#locator.selectOption(values, options);
+  }
+  async selectText(options) {
+    return this.#locator.selectText(options);
+  }
+  async check(options) {
+    return this.#locator.check(options);
+  }
+  async uncheck(options) {
+    return this.#locator.uncheck(options);
+  }
+  async setChecked(checked, options) {
+    return this.#locator.setChecked(checked, options);
+  }
+  async scrollIntoViewIfNeeded(options) {
+    return this.#locator.scrollIntoViewIfNeeded(options);
+  }
+  async screenshot(options) {
+    return this.#locator.screenshot(options);
+  }
+  async dragTo(target, options) {
+    const dest = target instanceof _SmartAction ? target.rawLocator : target;
+    return this.#locator.dragTo(dest, options);
+  }
+  async waitFor(options) {
+    return this.#locator.waitFor(options);
+  }
+  async waitForVisible(timeout = 3e4) {
+    return this.#locator.waitFor({ state: "visible", timeout });
+  }
+  async waitForHidden(timeout = 3e4) {
+    return this.#locator.waitFor({ state: "hidden", timeout });
+  }
+  async waitForAttached(timeout = 3e4) {
+    return this.#locator.waitFor({ state: "attached", timeout });
+  }
+  async waitForDetached(timeout = 3e4) {
+    return this.#locator.waitFor({ state: "detached", timeout });
+  }
+  async isVisible() {
+    return this.#locator.isVisible();
+  }
+  async isHidden() {
+    return this.#locator.isHidden();
+  }
+  async isEnabled() {
+    return this.#locator.isEnabled();
+  }
+  async isDisabled() {
+    return this.#locator.isDisabled();
+  }
+  async isChecked() {
+    return this.#locator.isChecked();
+  }
+  async isEditable() {
+    return this.#locator.isEditable();
+  }
+  async textContent() {
+    return this.#locator.textContent();
+  }
+  async innerText() {
+    return this.#locator.innerText();
+  }
+  async innerHTML() {
+    return this.#locator.innerHTML();
+  }
+  async inputValue(options) {
+    return this.#locator.inputValue(options);
+  }
+  async getAttribute(name) {
+    return this.#locator.getAttribute(name);
+  }
+  async boundingBox() {
+    return this.#locator.boundingBox();
+  }
+  async count() {
+    return this.#locator.count();
+  }
+  async allTextContents() {
+    return this.#locator.allTextContents();
+  }
+  async allInnerTexts() {
+    return this.#locator.allInnerTexts();
+  }
+  async all() {
+    return this.#locator.all();
+  }
+  async evaluate(pageFunction, arg) {
+    return this.#locator.evaluate(pageFunction, arg);
+  }
+  async evaluateAll(pageFunction, arg) {
+    return this.#locator.evaluateAll(pageFunction, arg);
+  }
+  async evaluateHandle(pageFunction, arg) {
+    return this.#locator.evaluateHandle(pageFunction, arg);
+  }
+  first() {
+    return this.#locator.first();
+  }
+  last() {
+    return this.#locator.last();
+  }
+  nth(index) {
+    return this.#locator.nth(index);
+  }
+  filter(options) {
+    return this.#locator.filter(options);
+  }
+  getByRole(role, options) {
+    return this.#locator.getByRole(role, options);
+  }
+  getByText(text, options) {
+    return this.#locator.getByText(text, options);
+  }
+  getByLabel(text, options) {
+    return this.#locator.getByLabel(text, options);
+  }
+  getByPlaceholder(text, options) {
+    return this.#locator.getByPlaceholder(text, options);
+  }
+  getByTestId(testId) {
+    return this.#locator.getByTestId(testId);
+  }
+  locator(selectorOrLocator, options) {
+    return this.#locator.locator(selectorOrLocator, options);
+  }
+  async highlight() {
+    return this.#locator.highlight();
+  }
+  async exists() {
+    return await this.#locator.count() > 0;
+  }
+  async getValue() {
+    try {
+      return await this.#locator.inputValue();
+    } catch {
+      return await this.#locator.textContent();
+    }
+  }
+  async getClasses() {
+    const cls = await this.#locator.getAttribute("class");
+    return cls ? cls.split(/\s+/).filter(Boolean) : [];
+  }
+  async hasClass(className) {
+    return (await this.getClasses()).includes(className);
+  }
+  async getCssProperty(property) {
+    return this.#locator.evaluate(
+      (el, prop) => window.getComputedStyle(el).getPropertyValue(prop),
+      property
+    );
+  }
+  toString() {
+    return `SmartAction("${this.#query}" \u2192 ${this.#result?.locatorString || "unknown"})`;
+  }
+};
+
+// src/smart-locator.js
+function clearCache() {
+  clearMemoryCache();
+}
+function clearAllCaches() {
+  clearMemoryCache();
+  clearDiskCache();
+}
+function createSmartLocator(page, options = {}) {
+  const { verbose = false } = options;
+  async function resolve(query, action) {
+    const { locator, result } = await getLocator(page, query, { ...options, action });
+    if (verbose) console.log(`[Smart Locator] ${action || "locate"}("${query}") \u2192 ${result.locatorString} (${result.source})`);
+    return new SmartAction(locator, result, query);
+  }
+  return {
+    async prefetch(...queries) {
+      const t0 = Date.now();
+      const results = await resolveLocatorsBatch(page, queries, options);
+      if (verbose) console.log(`[Smart Locator] Prefetched ${results.size} locators in ${Date.now() - t0}ms`);
+      return results;
+    },
+    async locate(query, action) {
+      return resolve(query, action || null);
+    },
+    async click(query, clickOptions) {
+      const el = await resolve(query, "click");
+      await el.click(clickOptions);
+      return el;
+    },
+    async dblclick(query, clickOptions) {
+      const el = await resolve(query, "click");
+      await el.dblclick(clickOptions);
+      return el;
+    },
+    async fill(query, value, fillOptions) {
+      const el = await resolve(query, "fill");
+      await el.fill(value, fillOptions);
+      return el;
+    },
+    async type(query, text, typeOptions) {
+      const el = await resolve(query, "fill");
+      await el.type(text, typeOptions);
+      return el;
+    },
+    async pressSequentially(query, text, pressOptions) {
+      const el = await resolve(query, "fill");
+      await el.pressSequentially(text, pressOptions);
+      return el;
+    },
+    async clear(query) {
+      const el = await resolve(query, "fill");
+      await el.clear();
+      return el;
+    },
+    async press(query, key, pressOptions) {
+      const el = await resolve(query, "fill");
+      await el.press(key, pressOptions);
+      return el;
+    },
+    async check(query, checkOptions) {
+      const el = await resolve(query, "check");
+      await el.check(checkOptions);
+      return el;
+    },
+    async uncheck(query, uncheckOptions) {
+      const el = await resolve(query, "uncheck");
+      await el.uncheck(uncheckOptions);
+      return el;
+    },
+    async setChecked(query, checked, checkOptions) {
+      const el = await resolve(query, checked ? "check" : "uncheck");
+      await el.setChecked(checked, checkOptions);
+      return el;
+    },
+    async select(query, values, selectOptions) {
+      const el = await resolve(query, "select");
+      await el.selectOption(values, selectOptions);
+      return el;
+    },
+    async hover(query, hoverOptions) {
+      const el = await resolve(query, "hover");
+      await el.hover(hoverOptions);
+      return el;
+    },
+    async focus(query) {
+      const el = await resolve(query, "click");
+      await el.focus();
+      return el;
+    },
+    async tap(query, tapOptions) {
+      const el = await resolve(query, "click");
+      await el.tap(tapOptions);
+      return el;
+    },
+    async setInputFiles(query, files, fileOptions) {
+      const el = await resolve(query, "fill");
+      await el.setInputFiles(files, fileOptions);
+      return el;
+    },
+    async dragTo(srcQuery, destQuery, dragOptions) {
+      const src = await resolve(srcQuery, "click");
+      const dest = await resolve(destQuery, "click");
+      await src.dragTo(dest, dragOptions);
+      return { source: src, target: dest };
+    },
+    async selectText(query) {
+      const el = await resolve(query, "click");
+      await el.selectText();
+      return el;
+    },
+    async scrollIntoView(query) {
+      const el = await resolve(query, null);
+      await el.scrollIntoViewIfNeeded();
+      return el;
+    },
+    async screenshot(query, screenshotOptions) {
+      const el = await resolve(query, null);
+      return el.screenshot(screenshotOptions);
+    },
+    async highlight(query) {
+      const el = await resolve(query, null);
+      await el.highlight();
+      return el;
+    },
+    async waitFor(query, waitOptions) {
+      const el = await resolve(query, null);
+      await el.waitFor(waitOptions);
+      return el;
+    },
+    async waitForVisible(query, timeout) {
+      const el = await resolve(query, null);
+      await el.waitForVisible(timeout);
+      return el;
+    },
+    async waitForHidden(query, timeout) {
+      const el = await resolve(query, null);
+      await el.waitForHidden(timeout);
+      return el;
+    },
+    async waitForAttached(query, timeout) {
+      const el = await resolve(query, null);
+      await el.waitForAttached(timeout);
+      return el;
+    },
+    async waitForDetached(query, timeout) {
+      const el = await resolve(query, null);
+      await el.waitForDetached(timeout);
+      return el;
+    },
+    async isVisible(query) {
+      try {
+        const el = await resolve(query, null);
+        return await el.isVisible();
+      } catch {
+        return false;
+      }
+    },
+    async isHidden(query) {
+      try {
+        const el = await resolve(query, null);
+        return await el.isHidden();
+      } catch {
+        return true;
+      }
+    },
+    async isEnabled(query) {
+      try {
+        const el = await resolve(query, null);
+        return await el.isEnabled();
+      } catch {
+        return false;
+      }
+    },
+    async isDisabled(query) {
+      try {
+        const el = await resolve(query, null);
+        return await el.isDisabled();
+      } catch {
+        return true;
+      }
+    },
+    async isChecked(query) {
+      try {
+        const el = await resolve(query, null);
+        return await el.isChecked();
+      } catch {
+        return false;
+      }
+    },
+    async isEditable(query) {
+      try {
+        const el = await resolve(query, null);
+        return await el.isEditable();
+      } catch {
+        return false;
+      }
+    },
+    async exists(query) {
+      try {
+        const el = await resolve(query, null);
+        return await el.exists();
+      } catch {
+        return false;
+      }
+    },
+    async getText(query) {
+      const el = await resolve(query, "getText");
+      return el.textContent();
+    },
+    async getInnerText(query) {
+      const el = await resolve(query, "getText");
+      return el.innerText();
+    },
+    async getInnerHTML(query) {
+      const el = await resolve(query, "getText");
+      return el.innerHTML();
+    },
+    async getInputValue(query) {
+      const el = await resolve(query, "fill");
+      return el.inputValue();
+    },
+    async getAttribute(query, attr) {
+      const el = await resolve(query, null);
+      return el.getAttribute(attr);
+    },
+    async getBoundingBox(query) {
+      const el = await resolve(query, null);
+      return el.boundingBox();
+    },
+    async count(query) {
+      const el = await resolve(query, null);
+      return el.count();
+    },
+    clearCache() {
+      clearCache();
+    },
+    clearAllCaches() {
+      clearAllCaches();
+    }
+  };
+}
+
+// src/llm-locator.js
+async function findLocator(page, query, options = {}) {
+  try {
+    const { result } = await getLocator(page, query, options);
+    return {
+      found: true,
+      strategy: result.strategy,
+      locatorString: result.locatorString,
+      locatorType: result.strategy,
+      confidence: result.confidence,
+      fullLocatorString: result.locatorString,
+      reasoning: result.reasoning,
+      isInFrame: result.isInFrame,
+      frameSelector: result.frameSelector,
+      fallbackLocators: result.fallbackLocators || [],
+      element: { strategy: result.strategy }
+    };
+  } catch (e) {
+    return { found: false, locatorString: null, confidence: 0, error: e.message };
+  }
+}
+async function findAllMatches(page, query, options = {}) {
+  try {
+    const { result } = await getLocator(page, query, options);
+    return result.found ? [result] : [];
+  } catch {
+    return [];
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SmartAction,
+  chatCompletion,
+  clearAllCaches,
+  clearCache,
+  createSmartLocator,
+  findAllMatches,
+  findLocator,
+  getConfig,
+  getLocator,
+  getPageStructure,
+  resolveLocator,
+  resolveLocatorsBatch
+});
+//# sourceMappingURL=index.cjs.map