playwright-genie 1.0.0 → 2.0.0

package/dist/index.js

@@ -1,107 +1,23 @@
-// src/llm/client.js
-import "dotenv/config";
-import OpenAI from "openai";
-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 OpenAI({
-  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" }]`
-    }
-  ];
-}
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
 
 // src/llm/parser.js
+var parser_exports = {};
+__export(parser_exports, {
+  applyChain: () => applyChain,
+  createPlaywrightLocator: () => createPlaywrightLocator,
+  evalLocator: () => evalLocator,
+  parseJsonResponse: () => parseJsonResponse,
+  validateLocator: () => validateLocator,
+  validateWithFallback: () => validateWithFallback
+});
 function parseJsonResponse(raw) {
   let text = raw.trim();
   if (text.startsWith("```")) {
@@ -121,17 +37,39 @@ function createPlaywrightLocator(page, locatorString, isInFrame, frameSelector)
 function parseInlineOptions(str) {
   if (!str) return {};
   const opts = {};
-  const nameRegex = str.match(/name:\s*\/([^/]+)\/([gimsuy]*)/);
-  const nameStr = str.match(/name:\s*'([^']+)'/);
+  let nameMatch = null;
+  const nameIdx = str.indexOf("name:");
+  if (nameIdx !== -1) {
+    const after = str.substring(nameIdx + 5).trim();
+    if (after.startsWith("/")) {
+      const lastSlash = after.lastIndexOf("/");
+      if (lastSlash > 0) {
+        const body = after.substring(1, lastSlash);
+        const flags = after.substring(lastSlash + 1).match(/^[gimsuy]*/)[0];
+        try {
+          opts.name = new RegExp(body, flags || void 0);
+        } catch {
+          opts.name = body;
+        }
+      }
+    } else if (after.startsWith("'")) {
+      const end = after.indexOf("'", 1);
+      if (end > 0) opts.name = after.substring(1, end);
+    }
+  }
   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);
+  if (regexBody) {
+    try {
+      return new RegExp(regexBody, regexFlags || void 0);
+    } catch {
+      return regexBody;
+    }
+  }
   return null;
 }
 function parseFilterOptions(str) {
@@ -146,7 +84,7 @@ function parseFilterOptions(str) {
 function evalLocator(context, code) {
   const patterns = [
     {
-      regex: /getByRole\('([^']+)'(?:,\s*({[^}]+}))?\)(.*)/,
+      regex: /getByRole\('([^']+)'(?:,\s*(\{.*\}))?\)(.*)/,
       handler: (m) => {
         const opts = parseInlineOptions(m[2]);
         return applyChain(context.getByRole(m[1], opts), m[3]);
@@ -196,9 +134,21 @@ function evalLocator(context, code) {
         return applyChain(context.getByTitle(t, opts), m[5]);
       }
     },
+    {
+      regex: /locator\('xpath=([^']+)'\)(.*)/,
+      handler: (m) => applyChain(context.locator(`xpath=${m[1]}`), m[2])
+    },
+    {
+      regex: /locator\("xpath=([^"]+)"\)(.*)/,
+      handler: (m) => applyChain(context.locator(`xpath=${m[1]}`), m[2])
+    },
     {
       regex: /locator\('([^']+)'\)(.*)/,
       handler: (m) => applyChain(context.locator(m[1]), m[2])
+    },
+    {
+      regex: /locator\("([^"]+)"\)(.*)/,
+      handler: (m) => applyChain(context.locator(m[1]), m[2])
     }
   ];
   for (const p of patterns) {
@@ -231,6 +181,243 @@ async function validateLocator(locator, timeoutMs = 3e3) {
     return false;
   }
 }
+async function validateWithFallback(page, primary, fallbacks, isInFrame, frameSelector) {
+  const primaryLocator = createPlaywrightLocator(page, primary, isInFrame, frameSelector);
+  const valid = await validateLocator(primaryLocator);
+  if (valid) return { locator: primaryLocator, locatorString: primary };
+  if (fallbacks && fallbacks.length > 0) {
+    for (const fb of fallbacks) {
+      try {
+        const fbLocator = createPlaywrightLocator(page, fb, isInFrame, frameSelector);
+        const fbValid = await validateLocator(fbLocator, 2e3);
+        if (fbValid) return { locator: fbLocator, locatorString: fb };
+      } catch {
+      }
+    }
+  }
+  return null;
+}
+var init_parser = __esm({
+  "src/llm/parser.js"() {
+  }
+});
+
+// src/llm/client.js
+import "dotenv/config";
+import OpenAI from "openai";
+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 OpenAI({
+  baseURL: LLM_BASE_URL,
+  apiKey: LLM_API_KEY
+});
+async function chatCompletion(messages, options = {}) {
+  const {
+    model = LLM_MODEL,
+    temperature = 0,
+    maxTokens = 256
+  } = options;
+  if (DEBUG) {
+    console.log(`[LLM Client] model=${model} base=${LLM_BASE_URL} msgs=${messages.length}`);
+  }
+  const params = {
+    model,
+    temperature,
+    max_tokens: maxTokens,
+    messages
+  };
+  if (model.includes("gpt-") || model.includes("o1") || model.includes("o3") || model.includes("o4")) {
+    params.response_format = { type: "json_object" };
+  }
+  const completion = await client.chat.completions.create(params);
+  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, special DOM elements, and interactive 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.
+6. NEVER invent accessible names. If an element appears in the aria tree WITHOUT a quoted name
+   (e.g., "textbox", "button", "checkbox", "combobox", "link" with no "Name" after it),
+   it has NO accessible name. Do NOT guess a name from nearby text, labels, cells, or headings.
+   Instead, find that element in interactiveElements by matching tag/type/position, then use its
+   id, htmlName, testId, or selector to build a CSS locator:
+   - page.locator('#escapedId')
+   - page.locator('[name="htmlName"]')
+   - page.locator('[data-test="value"]')
+   - page.locator('select.className')
+   Only use getByRole('role', { name: /text/i }) when the aria tree EXPLICITLY shows a quoted name
+   like: button "Submit", link "Home", textbox "Email".
+
+INTERACTIVE ELEMENTS:
+- The interactiveElements array contains DOM metadata for ALL interactive elements including unnamed ones.
+- Each entry has: tag, type, role, id, classes, name, testId, text, options (for selects), selector, parentContext.
+- When an element has NO accessible name in the aria tree, use interactiveElements to find it by id, testId, classes, or parent context.
+- For <select> elements: use the "selector" or "id" field to build page.locator('#id') or page.getByTestId('...').
+- For unnamed comboboxes: look at interactiveElements for a select/combobox with matching options, then use its id/testId/classes.
+
+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, listbox, or <select> element. If the element is a native <select>, prefer page.locator('#id') or page.locator('select.className').
+- If action is "getText" or null: Target any matching element.
+
+LOCATOR PRIORITY: getByTestId > getByRole > getByLabel > getByPlaceholder > getByAltText > getByTitle > getByText > locator(CSS)
+FALLBACK: When no accessible name exists, use locator('CSS selector') with id, class, or data attribute from interactiveElements.
+- When using test IDs, use the EXACT attribute from the page data.
+- If data shows [data-test="x"], use page.locator('[data-test="x"]') NOT getByTestId('x').
+- Only use getByTestId() if the attribute is literally "data-testid".
+For iframes: page.frameLocator('sel').getByRole(...)
+For positional: .first() / .nth(n) / .last()
+
+Return ONLY valid JSON.`;
+var DOM_SYSTEM_PROMPT = `You are an expert at generating Playwright locators from raw DOM structure.
+You receive a DOM tree with element metadata (tag, id, classes, xpath, css selectors, text, attributes).
+There is NO accessibility tree available \u2014 you must build locators purely from DOM data.
+
+CRITICAL RULES:
+1. The user's query is a DESCRIPTION of the element, NOT the element's text. Match the description to DOM nodes.
+2. ONLY use data that EXISTS in the provided DOM structure. NEVER invent IDs, classes, or text.
+3. Each DOM node may have: tag, id, classes, role, testId ({attr, value}), ariaLabel, title, name, placeholder, text, href, xpath, css, label, type, value, disabled, checked, depth, interactive, heading, landmark.
+
+LOCATOR STRATEGY (in priority order):
+1. Test ID: If testId exists, use page.locator('[<attr>="<value>"]') with the EXACT attribute name.
+   Only use page.getByTestId('x') when attr is literally "data-testid".
+2. ID: page.locator('#<id>') \u2014 most stable, prefer when available.
+3. Role + accessible name: page.getByRole('<role>', { name: /<text>/i }) \u2014 when role and ariaLabel/label/text exist.
+4. Label: page.getByLabel(/<text>/i) \u2014 for form fields with associated labels.
+5. Placeholder: page.getByPlaceholder(/<text>/i) \u2014 for inputs with placeholder text.
+6. Name attribute: page.locator('[name="<name>"]') \u2014 for form elements.
+7. CSS selector: page.locator('<css>') \u2014 use the "css" field from DOM data when available.
+8. XPath: page.locator('xpath=<xpath>') \u2014 use as last resort, take from "xpath" field.
+9. Compound CSS: Build from tag + class + structural position when no unique identifier exists.
+   Example: page.locator('div.container button.submit')
+   Example: page.locator('form#login input[type="email"]')
+
+COMBINING SELECTORS FOR UNIQUENESS:
+- If a single attribute isn't unique, combine: page.locator('form#login input[name="email"]')
+- Use parent context from "depth" and surrounding nodes to disambiguate.
+- Use .first() / .nth(n) / .last() when multiple matches exist.
+- Use .filter({ hasText: /text/i }) to narrow results.
+
+ACTION-AWARE RULES:
+- If action is "fill", "type", "clear", "press": Target MUST be input, textarea, select, or [contenteditable]. NEVER target labels, divs, or spans.
+- If action is "click": Target the clickable element (button, a, [role="button"], etc).
+- If action is "check", "uncheck": Target checkbox or radio input.
+- If action is "select": Target the <select> element or [role="combobox"]/[role="listbox"].
+
+FALLBACK LOCATORS:
+- Always provide 1-2 fallback locators in case the primary doesn't match.
+- Use different strategies for fallbacks (e.g., primary=CSS, fallback=XPath).
+
+For iframes: page.frameLocator('sel').locator(...)
+Return ONLY valid JSON.`;
+function buildMessages(pageStructure, query, action) {
+  const actionNote = action ? `
+ACTION: The user wants to "${action}" this element.` : "";
+  return [
+    { role: "system", content: SYSTEM_PROMPT },
+    {
+      role: "user",
+      content: `Page structure:
+${pageStructure}
+
+Find element: "${query}"${actionNote}
+
+IMPORTANT: Find the element that matches the description "${query}". Do NOT use "${query}" as the locator text - find the ACTUAL element name/text from the page structure above.
+
+Return JSON: {"locatorString":"page.getBy...(...)", "confidence": 0.0-1.0, "explanation":"...", "fallbackLocators":["page.locator(...)"]}`
+    }
+  ];
+}
+function buildDomMessages(pageStructure, query, action) {
+  const actionNote = action ? `
+ACTION: The user wants to "${action}" this element.` : "";
+  return [
+    { role: "system", content: DOM_SYSTEM_PROMPT },
+    {
+      role: "user",
+      content: `DOM structure:
+${pageStructure}
+
+Find element: "${query}"${actionNote}
+
+INSTRUCTIONS:
+- Search the domTree and interactiveElements for the element matching "${query}".
+- Use the element's id, testId, css, xpath, name, classes, role, text, label, or placeholder to build a Playwright locator.
+- Prefer stable selectors (id, testId, name) over positional ones (xpath, nth).
+- Provide fallback locators using alternative strategies.
+
+Return JSON: {"locatorString":"page.locator(...)", "confidence": 0.0-1.0, "explanation":"...", "fallbackLocators":["page.locator('xpath=...')"]}`
+    }
+  ];
+}
+function buildBatchMessages(pageStructure, queries) {
+  const queryList = queries.map((q, i) => `${i + 1}. "${q.query || q}" (action: ${q.action || "none"})`).join("\n");
+  return [
+    { role: "system", content: SYSTEM_PROMPT },
+    {
+      role: "user",
+      content: `Page structure:
+${pageStructure}
+
+Find ALL of these elements:
+${queryList}
+
+IMPORTANT: For each query, find the ACTUAL element name/text from the page structure. Do NOT echo the query as locator text.
+
+Return JSON array: [{"query":"...","locatorString":"page.getBy...(...)", "confidence": 0.0-1.0, "explanation":"...", "fallbackLocators":["..."]}]`
+    }
+  ];
+}
+function buildDomBatchMessages(pageStructure, queries) {
+  const queryList = queries.map((q, i) => `${i + 1}. "${q.query || q}" (action: ${q.action || "none"})`).join("\n");
+  return [
+    { role: "system", content: DOM_SYSTEM_PROMPT },
+    {
+      role: "user",
+      content: `DOM structure:
+${pageStructure}
+
+Find ALL of these elements:
+${queryList}
+
+INSTRUCTIONS:
+- Search the domTree and interactiveElements for each element.
+- Use id, testId, css, xpath, name, classes, role, text, label, or placeholder to build Playwright locators.
+- Prefer stable selectors over positional ones.
+
+Return JSON array: [{"query":"...","locatorString":"page.locator(...)", "confidence": 0.0-1.0, "explanation":"...", "fallbackLocators":["..."]}]`
+    }
+  ];
+}
+
+// src/resolver.js
+init_parser();
 
 // src/cache/disk-cache.js
 import fs from "fs";
@@ -356,6 +543,8 @@ function clearMemoryCache() {
 
 // src/page-structure.js
 var DEBUG3 = process.env.LLM_LOCATOR_DEBUG === "true";
+var MAX_DOM_NODES = 300;
+var MAX_INTERACTIVE = 100;
 async function getPageStructure(page, forceRefresh = false) {
   const url = page.url();
   if (!forceRefresh && isStructureCacheValid(url)) {
@@ -382,7 +571,9 @@ async function getPageStructure(page, forceRefresh = false) {
 async function getFrameStructure(pageOrFrame) {
   let ariaTree = null;
   let specialElements = [];
-  const [ariaResult, domResult] = await Promise.allSettled([
+  let interactiveElements = [];
+  let domTree = [];
+  const [ariaResult, domResult, interactiveResult, domTreeResult] = await Promise.allSettled([
     pageOrFrame.locator("body").ariaSnapshot({ timeout: 5e3 }),
     pageOrFrame.evaluate(() => {
       const els = [];
@@ -399,7 +590,220 @@ async function getFrameStructure(pageOrFrame) {
         if (e.testId || e.placeholder || e.alt || e.ariaLabel) els.push(e);
       }
       return els;
-    })
+    }),
+    pageOrFrame.evaluate((maxInteractive) => {
+      const els = [];
+      const selectors = 'select, input, textarea, button, a, [role="combobox"], [role="listbox"], [role="menu"], [role="tab"], [role="checkbox"], [role="radio"], [role="slider"], [role="switch"], [contenteditable="true"]';
+      for (const el of document.querySelectorAll(selectors)) {
+        if (els.length >= maxInteractive) break;
+        const ariaLabel = el.getAttribute("aria-label") || el.getAttribute("placeholder") || null;
+        const htmlName = el.getAttribute("name") || null;
+        const id = el.id || null;
+        const classes = el.className ? el.className.toString().split(/\s+/).filter((c) => c && c.length < 40).slice(0, 3).join(" ") : null;
+        const tag = el.tagName.toLowerCase();
+        const type = el.getAttribute("type") || null;
+        const role = el.getAttribute("role") || null;
+        const testIdAttr = el.getAttribute("data-testid") ? "data-testid" : el.getAttribute("data-test") ? "data-test" : el.getAttribute("data-test-id") ? "data-test-id" : el.getAttribute("data-qa") ? "data-qa" : el.getAttribute("data-cy") ? "data-cy" : null;
+        const testId = testIdAttr ? el.getAttribute(testIdAttr) : null;
+        const text = el.textContent?.trim().substring(0, 50) || null;
+        const labelEl = id ? document.querySelector(`label[for="${id}"]`) : null;
+        const labelText = labelEl ? labelEl.textContent.trim().substring(0, 50) : null;
+        let options = null;
+        if (tag === "select") {
+          options = [...el.options].map((o) => ({ value: o.value, text: o.text, selected: o.selected })).slice(0, 10);
+        }
+        const parent = el.closest("[class], [id], [data-testid], [data-test], [data-cy], [data-qa]");
+        let parentContext = null;
+        if (parent && parent !== el) {
+          const parentTestAttr = parent.getAttribute("data-testid") ? "data-testid" : parent.getAttribute("data-test") ? "data-test" : parent.getAttribute("data-qa") ? "data-qa" : parent.getAttribute("data-cy") ? "data-cy" : null;
+          parentContext = parent.id ? `#${parent.id}` : parentTestAttr ? `[${parentTestAttr}="${parent.getAttribute(parentTestAttr)}"]` : parent.className ? `.${parent.className.toString().split(/\s+/)[0]}` : null;
+        }
+        const selector = testId ? `[${testIdAttr}="${testId}"]` : id ? `[id="${id}"]` : htmlName ? `[name="${htmlName}"]` : classes ? `.${classes.split(" ")[0]}` : null;
+        els.push({
+          tag,
+          type,
+          role,
+          id,
+          classes,
+          ariaLabel,
+          htmlName,
+          testId,
+          labelText,
+          text: tag === "select" ? null : text,
+          options,
+          selector,
+          parentContext
+        });
+      }
+      return els;
+    }, MAX_INTERACTIVE),
+    pageOrFrame.evaluate((maxNodes) => {
+      function getXPath(el) {
+        if (el.id) return `//*[@id="${el.id}"]`;
+        const parts = [];
+        let current = el;
+        while (current && current.nodeType === 1) {
+          let idx = 0;
+          let sibling = current.previousSibling;
+          while (sibling) {
+            if (sibling.nodeType === 1 && sibling.tagName === current.tagName) idx++;
+            sibling = sibling.previousSibling;
+          }
+          const tag = current.tagName.toLowerCase();
+          parts.unshift(idx > 0 || current.nextElementSibling?.tagName === current.tagName ? `${tag}[${idx + 1}]` : tag);
+          current = current.parentElement;
+        }
+        return "/" + parts.join("/");
+      }
+      function getUniqueSelector(el) {
+        if (el.id) return `#${CSS.escape(el.id)}`;
+        const testAttrs = ["data-testid", "data-test-id", "data-test", "data-qa", "data-cy"];
+        for (const attr of testAttrs) {
+          const val = el.getAttribute(attr);
+          if (val) return `[${attr}="${CSS.escape(val)}"]`;
+        }
+        const tag = el.tagName.toLowerCase();
+        const name = el.getAttribute("name");
+        if (name) return `${tag}[name="${CSS.escape(name)}"]`;
+        const cls = el.className?.toString().trim();
+        if (cls) {
+          const sel = tag + "." + cls.split(/\s+/).map((c) => CSS.escape(c)).join(".");
+          if (document.querySelectorAll(sel).length === 1) return sel;
+        }
+        return null;
+      }
+      function isVisible(el) {
+        if (!el.offsetParent && el.tagName !== "BODY" && el.tagName !== "HTML" && getComputedStyle(el).position !== "fixed" && getComputedStyle(el).position !== "sticky") return false;
+        const style = getComputedStyle(el);
+        return style.display !== "none" && style.visibility !== "hidden" && parseFloat(style.opacity) > 0;
+      }
+      const interactiveTags = /* @__PURE__ */ new Set([
+        "a",
+        "button",
+        "input",
+        "textarea",
+        "select",
+        "details",
+        "summary",
+        "label"
+      ]);
+      const interactiveRoles = /* @__PURE__ */ new Set([
+        "button",
+        "link",
+        "tab",
+        "menuitem",
+        "menuitemcheckbox",
+        "menuitemradio",
+        "option",
+        "checkbox",
+        "radio",
+        "switch",
+        "slider",
+        "spinbutton",
+        "combobox",
+        "listbox",
+        "searchbox",
+        "textbox",
+        "treeitem"
+      ]);
+      const landmarkRoles = /* @__PURE__ */ new Set([
+        "banner",
+        "navigation",
+        "main",
+        "complementary",
+        "contentinfo",
+        "form",
+        "region",
+        "search",
+        "dialog",
+        "alertdialog",
+        "tablist",
+        "toolbar",
+        "menu",
+        "menubar",
+        "tree",
+        "grid",
+        "table",
+        "list"
+      ]);
+      const structuralSel = "h1, h2, h3, h4, h5, h6, nav, main, header, footer, section, form, table, thead, tbody, tr, th, td, ul, ol, li, dl, dt, dd, fieldset, legend, [role]";
+      const nodes = [];
+      const allEls = document.querySelectorAll("body *");
+      for (const el of allEls) {
+        if (nodes.length >= maxNodes) break;
+        const tag = el.tagName.toLowerCase();
+        if (["script", "style", "noscript", "br", "hr", "wbr", "meta", "link"].includes(tag)) continue;
+        if (!isVisible(el)) continue;
+        const role = el.getAttribute("role") || null;
+        const isInteractive = interactiveTags.has(tag) || role && interactiveRoles.has(role) || el.getAttribute("contenteditable") === "true" || el.getAttribute("tabindex") !== null || el.getAttribute("onclick") !== null;
+        const isLandmark = landmarkRoles.has(role) || ["nav", "main", "header", "footer", "section", "form", "table"].includes(tag);
+        const isHeading = /^h[1-6]$/.test(tag);
+        const isStructural = el.matches(structuralSel);
+        if (!isInteractive && !isLandmark && !isHeading && !isStructural) continue;
+        const id = el.id || null;
+        const classes = el.className ? el.className.toString().split(/\s+/).filter((c) => c && c.length < 50).slice(0, 5).join(" ") : null;
+        const text = (el.textContent?.trim() || "").substring(0, 80) || null;
+        const directText = (() => {
+          let t = "";
+          for (const child of el.childNodes) {
+            if (child.nodeType === 3) t += child.textContent;
+          }
+          return t.trim().substring(0, 80) || null;
+        })();
+        const ariaLabel = el.getAttribute("aria-label") || null;
+        const title = el.getAttribute("title") || null;
+        const type = el.getAttribute("type") || null;
+        const href = tag === "a" ? (el.getAttribute("href") || "").substring(0, 100) : null;
+        const placeholder = el.getAttribute("placeholder") || null;
+        const htmlName = el.getAttribute("name") || null;
+        const value = tag === "input" || tag === "textarea" ? (el.value || "").substring(0, 50) || null : null;
+        const disabled = el.disabled || el.getAttribute("aria-disabled") === "true" || null;
+        const checked = el.checked !== void 0 ? el.checked : null;
+        const testIdAttr = el.getAttribute("data-testid") ? "data-testid" : el.getAttribute("data-test") ? "data-test" : el.getAttribute("data-test-id") ? "data-test-id" : el.getAttribute("data-qa") ? "data-qa" : el.getAttribute("data-cy") ? "data-cy" : null;
+        const testId = testIdAttr ? { attr: testIdAttr, value: el.getAttribute(testIdAttr) } : null;
+        const xpath = getXPath(el);
+        const cssSelector = getUniqueSelector(el);
+        const depth = (() => {
+          let d = 0;
+          let p = el.parentElement;
+          while (p && p !== document.body) {
+            d++;
+            p = p.parentElement;
+          }
+          return d;
+        })();
+        const node = { tag, depth };
+        if (role) node.role = role;
+        if (id) node.id = id;
+        if (classes) node.classes = classes;
+        if (testId) node.testId = testId;
+        if (ariaLabel) node.ariaLabel = ariaLabel;
+        if (title) node.title = title;
+        if (type) node.type = type;
+        if (htmlName) node.name = htmlName;
+        if (placeholder) node.placeholder = placeholder;
+        if (href) node.href = href;
+        if (directText) node.text = directText;
+        else if (text && text.length <= 80) node.text = text;
+        if (value) node.value = value;
+        if (disabled) node.disabled = true;
+        if (checked !== null && checked !== void 0) node.checked = checked;
+        if (isInteractive) node.interactive = true;
+        if (isHeading) node.heading = true;
+        if (isLandmark) node.landmark = true;
+        node.xpath = xpath;
+        if (cssSelector) node.css = cssSelector;
+        const labelEl = id ? document.querySelector(`label[for="${id}"]`) : null;
+        if (labelEl) node.label = labelEl.textContent.trim().substring(0, 50);
+        let selectOpts = null;
+        if (tag === "select") {
+          selectOpts = [...el.options].map((o) => ({ value: o.value, text: o.text, selected: o.selected })).slice(0, 15);
+          if (selectOpts.length) node.options = selectOpts;
+        }
+        nodes.push(node);
+      }
+      return nodes;
+    }, MAX_DOM_NODES)
   ]);
   if (ariaResult.status === "fulfilled") ariaTree = ariaResult.value;
   else {
@@ -412,7 +816,19 @@ async function getFrameStructure(pageOrFrame) {
     }
   }
   if (domResult.status === "fulfilled") specialElements = domResult.value;
-  return { ariaTree, specialElements };
+  if (interactiveResult.status === "fulfilled") interactiveElements = interactiveResult.value;
+  if (domTreeResult.status === "fulfilled") domTree = domTreeResult.value;
+  const ariaQuality = evaluateAriaQuality(ariaTree, interactiveElements.length);
+  return { ariaTree, specialElements, interactiveElements, domTree, ariaQuality };
+}
+function evaluateAriaQuality(ariaTree, interactiveCount) {
+  if (!ariaTree || typeof ariaTree !== "string") return "none";
+  const lines = ariaTree.split("\n").filter((l) => l.trim());
+  const namedInteractive = (ariaTree.match(/(button|link|textbox|combobox|checkbox|tab|radio|switch)\s+"[^"]+"/g) || []).length;
+  if (lines.length < 5) return "none";
+  if (namedInteractive < 3 && interactiveCount > 5) return "sparse";
+  if (lines.length < 20 && interactiveCount > 10) return "sparse";
+  return "good";
 }
 function simplifyAriaTree(node, depth = 0) {
   if (!node || depth > 8) return null;
@@ -466,30 +882,123 @@ function trimSnapshotForQuery(ariaYaml, query, maxLines = 150) {
   }
   return result.join("\n");
 }
+function filterDomTreeForQuery(domTree, query, maxNodes = 80) {
+  if (!domTree || !domTree.length) return domTree;
+  if (domTree.length <= maxNodes) return domTree;
+  const queryTokens = query.toLowerCase().replace(/[^a-z0-9\s]/g, "").split(/\s+/).filter(Boolean);
+  const scored = domTree.map((node, idx) => {
+    let score = 0;
+    if (node.interactive) score += 5;
+    if (node.heading) score += 3;
+    if (node.landmark) score += 2;
+    const searchable = [node.text, node.ariaLabel, node.label, node.placeholder, node.title, node.id, node.name, node.testId?.value].filter(Boolean).join(" ").toLowerCase();
+    for (const token of queryTokens) {
+      if (searchable.includes(token)) score += 15;
+    }
+    return { node, idx, score };
+  });
+  scored.sort((a, b) => b.score - a.score);
+  return scored.slice(0, maxNodes).sort((a, b) => a.idx - b.idx).map((s) => s.node);
+}
 
 // src/resolver.js
 var DEBUG4 = process.env.LLM_LOCATOR_DEBUG === "true";
+var PAYLOAD_LIMITS = {
+  good: 15e3,
+  sparse: 25e3,
+  none: 3e4
+};
 function buildPayload(pageStructure, query) {
+  const quality = pageStructure.mainFrame.ariaQuality || "good";
+  const maxPayload = PAYLOAD_LIMITS[quality] || PAYLOAD_LIMITS.good;
+  if (quality === "none") {
+    return buildDomOnlyPayload(pageStructure, query, maxPayload);
+  }
+  if (quality === "sparse") {
+    return buildHybridPayload(pageStructure, query, maxPayload);
+  }
+  return buildAriaPayload(pageStructure, query, maxPayload);
+}
+function buildAriaPayload(pageStructure, query, maxPayload) {
   const trimmedAria = trimSnapshotForQuery(pageStructure.mainFrame.ariaTree, query);
+  const specialElements = pageStructure.mainFrame.specialElements;
+  const interactiveElements = pageStructure.mainFrame.interactiveElements || [];
   const payload = {
+    mode: "aria",
     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
+    specialElements: specialElements.length > 30 ? specialElements.slice(0, 30) : specialElements,
+    interactiveElements: interactiveElements.length > 50 ? interactiveElements.slice(0, 50) : interactiveElements,
+    frames: buildFramesPayload(pageStructure, query)
   };
-  let payloadStr = JSON.stringify(payload, null, 2);
-  if (payloadStr.length > 15e3) payloadStr = payloadStr.substring(0, 15e3) + "\n...(truncated)";
-  return payloadStr;
+  let payloadStr = JSON.stringify(payload);
+  if (payloadStr.length > maxPayload) payloadStr = payloadStr.substring(0, maxPayload) + "...(truncated)";
+  return { payloadStr, mode: "aria" };
+}
+function buildHybridPayload(pageStructure, query, maxPayload) {
+  const trimmedAria = trimSnapshotForQuery(pageStructure.mainFrame.ariaTree, query);
+  const interactiveElements = pageStructure.mainFrame.interactiveElements || [];
+  const domTree = filterDomTreeForQuery(pageStructure.mainFrame.domTree || [], query, 120);
+  const payload = {
+    mode: "hybrid",
+    ariaTree: trimmedAria,
+    interactiveElements: interactiveElements.slice(0, 60),
+    domTree,
+    frames: buildFramesPayload(pageStructure, query)
+  };
+  let payloadStr = JSON.stringify(payload);
+  if (payloadStr.length > maxPayload) {
+    payload.domTree = filterDomTreeForQuery(pageStructure.mainFrame.domTree || [], query, 60);
+    payloadStr = JSON.stringify(payload);
+  }
+  if (payloadStr.length > maxPayload) payloadStr = payloadStr.substring(0, maxPayload) + "...(truncated)";
+  return { payloadStr, mode: "hybrid" };
+}
+function buildDomOnlyPayload(pageStructure, query, maxPayload) {
+  const interactiveElements = pageStructure.mainFrame.interactiveElements || [];
+  const domTree = filterDomTreeForQuery(pageStructure.mainFrame.domTree || [], query, 150);
+  const specialElements = pageStructure.mainFrame.specialElements || [];
+  const payload = {
+    mode: "dom",
+    domTree,
+    specialElements: specialElements.slice(0, 30),
+    interactiveElements: interactiveElements.slice(0, 80),
+    frames: buildFramesPayload(pageStructure, query)
+  };
+  let payloadStr = JSON.stringify(payload);
+  if (payloadStr.length > maxPayload) {
+    payload.domTree = filterDomTreeForQuery(pageStructure.mainFrame.domTree || [], query, 80);
+    payload.interactiveElements = interactiveElements.slice(0, 50);
+    payloadStr = JSON.stringify(payload);
+  }
+  if (payloadStr.length > maxPayload) payloadStr = payloadStr.substring(0, maxPayload) + "...(truncated)";
+  return { payloadStr, mode: "dom" };
+}
+function buildFramesPayload(pageStructure, query) {
+  if (!pageStructure.frames || pageStructure.frames.length === 0) return void 0;
+  return pageStructure.frames.map((f) => {
+    const frame = { selector: f.selector };
+    if (f.content?.ariaTree) {
+      frame.ariaTree = trimSnapshotForQuery(f.content.ariaTree, query, 50);
+    }
+    if (f.content?.specialElements) {
+      frame.specialElements = (f.content.specialElements || []).slice(0, 10);
+    }
+    if (f.content?.interactiveElements) {
+      frame.interactiveElements = (f.content.interactiveElements || []).slice(0, 20);
+    }
+    if (f.content?.domTree) {
+      frame.domTree = filterDomTreeForQuery(f.content.domTree || [], query, 30);
+    }
+    return frame;
+  });
 }
 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);
+  const { payloadStr, mode } = buildPayload(pageStructure, query);
+  if (DEBUG4) console.log(`[Resolver] mode=${mode} payload=${payloadStr.length} chars`);
+  const messages = mode === "dom" ? buildDomMessages(payloadStr, query, action) : mode === "hybrid" ? buildDomMessages(payloadStr, query, action) : buildMessages(payloadStr, query, action);
+  const maxTokens = mode === "aria" ? 256 : 512;
+  const raw = await chatCompletion(messages, { ...options, maxTokens });
   return parseJsonResponse(raw);
 }
 async function resolveLocator(page, query, options = {}) {
@@ -499,7 +1008,7 @@ async function resolveLocator(page, query, options = {}) {
   const memHit = getMemEntry(url, query, action);
   if (memHit) {
     if (shouldDebug) console.log(`[Memory Cache Hit] "${query}" \u2192 ${memHit.locatorString}`);
-    return memHit;
+    return { ...memHit, source: "memory" };
   }
   const diskHit = getDiskEntry(url, query, action);
   if (diskHit) {
@@ -557,6 +1066,17 @@ async function getLocator(page, query, options = {}) {
       bumpHitCount(url, query, action);
       return { locator, result };
     }
+    if (result.fallbackLocators && result.fallbackLocators.length > 0) {
+      if (shouldDebug) console.log(`[Fallback] Primary "${result.locatorString}" not found, trying ${result.fallbackLocators.length} fallbacks...`);
+      const fbResult = await validateWithFallback(page, result.locatorString, result.fallbackLocators, result.isInFrame, result.frameSelector);
+      if (fbResult && fbResult.locatorString !== result.locatorString) {
+        if (shouldDebug) console.log(`[Fallback] Using fallback: ${fbResult.locatorString}`);
+        const updatedResult = { ...result, locatorString: fbResult.locatorString, strategy: "fallback" };
+        setMemEntry(url, query, action, updatedResult);
+        setDiskEntry(url, query, action, updatedResult);
+        return { locator: fbResult.locator, result: updatedResult };
+      }
+    }
     if (shouldDebug) console.log(`[Stale Cache] "${query}" \u2192 ${result.locatorString} no longer valid, re-querying LLM...`);
     invalidateDiskEntry(url, query, action);
     deleteMemEntry(url, query, action);
@@ -566,6 +1086,20 @@ async function getLocator(page, query, options = {}) {
     const freshLocator = createPlaywrightLocator(page, freshResult.locatorString, freshResult.isInFrame, freshResult.frameSelector);
     return { locator: freshLocator, result: freshResult };
   }
+  if (result.source === "llm" && result.fallbackLocators && result.fallbackLocators.length > 0) {
+    const valid = await validateLocator(locator, 2e3);
+    if (!valid) {
+      if (shouldDebug) console.log(`[Fallback] Primary "${result.locatorString}" not found, trying ${result.fallbackLocators.length} fallbacks...`);
+      const fbResult = await validateWithFallback(page, result.locatorString, result.fallbackLocators, result.isInFrame, result.frameSelector);
+      if (fbResult && fbResult.locatorString !== result.locatorString) {
+        if (shouldDebug) console.log(`[Fallback] Using fallback: ${fbResult.locatorString}`);
+        const updatedResult = { ...result, locatorString: fbResult.locatorString, strategy: "fallback" };
+        setMemEntry(url, query, action, updatedResult);
+        setDiskEntry(url, query, action, updatedResult);
+        return { locator: fbResult.locator, result: updatedResult };
+      }
+    }
+  }
   return { locator, result };
 }
 async function resolveLocatorsBatch(page, queries, options = {}) {
@@ -601,11 +1135,11 @@ async function resolveLocatorsBatch(page, queries, options = {}) {
   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)";
+  const { payloadStr, mode } = buildPayload(pageStructure, uncached.join(" "));
   try {
-    const messages = buildBatchMessages(payloadStr, uncached);
-    const raw = await chatCompletion(messages, options);
+    const messages = mode === "dom" || mode === "hybrid" ? buildDomBatchMessages(payloadStr, uncached) : buildBatchMessages(payloadStr, uncached);
+    const maxTokens = mode === "aria" ? 256 : 512;
+    const raw = await chatCompletion(messages, { ...options, maxTokens });
     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++) {
@@ -655,66 +1189,84 @@ var SmartAction = class _SmartAction {
   get query() {
     return this.#query;
   }
+  async #safeAction(action, ...args) {
+    try {
+      return await this.#locator[action](...args);
+    } catch (err) {
+      if (err.message && err.message.includes("strict mode violation")) {
+        if (DEBUG5) console.log(`[SmartAction] Strict mode on "${this.#query}", retrying with .first()`);
+        return await this.#locator.first()[action](...args);
+      }
+      throw err;
+    }
+  }
   async click(options) {
-    return this.#locator.click(options);
+    return this.#safeAction("click", options);
   }
   async dblclick(options) {
-    return this.#locator.dblclick(options);
+    return this.#safeAction("dblclick", options);
   }
   async tap(options) {
-    return this.#locator.tap(options);
+    return this.#safeAction("tap", options);
   }
   async hover(options) {
-    return this.#locator.hover(options);
+    return this.#safeAction("hover", options);
   }
   async focus() {
-    return this.#locator.focus();
+    return this.#safeAction("focus");
   }
   async blur() {
-    return this.#locator.blur();
+    return this.#safeAction("blur");
   }
   async fill(value, options) {
-    return this.#locator.fill(value, options);
+    return this.#safeAction("fill", value, options);
   }
   async type(text, options) {
-    return this.#locator.type(text, options);
+    return this.#safeAction("type", text, options);
   }
   async press(key, options) {
-    return this.#locator.press(key, options);
+    return this.#safeAction("press", key, options);
   }
   async pressSequentially(text, options) {
-    return this.#locator.pressSequentially(text, options);
+    return this.#safeAction("pressSequentially", text, options);
   }
   async clear(options) {
-    return this.#locator.clear(options);
+    return this.#safeAction("clear", options);
   }
   async setInputFiles(files, options) {
-    return this.#locator.setInputFiles(files, options);
+    return this.#safeAction("setInputFiles", files, options);
   }
   async selectOption(values, options) {
-    return this.#locator.selectOption(values, options);
+    return this.#safeAction("selectOption", values, options);
   }
   async selectText(options) {
-    return this.#locator.selectText(options);
+    return this.#safeAction("selectText", options);
   }
   async check(options) {
-    return this.#locator.check(options);
+    return this.#safeAction("check", options);
   }
   async uncheck(options) {
-    return this.#locator.uncheck(options);
+    return this.#safeAction("uncheck", options);
   }
   async setChecked(checked, options) {
-    return this.#locator.setChecked(checked, options);
+    return this.#safeAction("setChecked", checked, options);
   }
   async scrollIntoViewIfNeeded(options) {
-    return this.#locator.scrollIntoViewIfNeeded(options);
+    return this.#safeAction("scrollIntoViewIfNeeded", options);
   }
   async screenshot(options) {
-    return this.#locator.screenshot(options);
+    return this.#safeAction("screenshot", options);
   }
   async dragTo(target, options) {
     const dest = target instanceof _SmartAction ? target.rawLocator : target;
-    return this.#locator.dragTo(dest, options);
+    try {
+      return await this.#locator.dragTo(dest, options);
+    } catch (err) {
+      if (err.message && err.message.includes("strict mode violation")) {
+        return await this.#locator.first().dragTo(dest, options);
+      }
+      throw err;
+    }
   }
   async waitFor(options) {
     return this.#locator.waitFor(options);
@@ -750,22 +1302,22 @@ var SmartAction = class _SmartAction {
     return this.#locator.isEditable();
   }
   async textContent() {
-    return this.#locator.textContent();
+    return this.#safeAction("textContent");
   }
   async innerText() {
-    return this.#locator.innerText();
+    return this.#safeAction("innerText");
   }
   async innerHTML() {
-    return this.#locator.innerHTML();
+    return this.#safeAction("innerHTML");
   }
   async inputValue(options) {
-    return this.#locator.inputValue(options);
+    return this.#safeAction("inputValue", options);
   }
   async getAttribute(name) {
-    return this.#locator.getAttribute(name);
+    return this.#safeAction("getAttribute", name);
   }
   async boundingBox() {
-    return this.#locator.boundingBox();
+    return this.#safeAction("boundingBox");
   }
   async count() {
     return this.#locator.count();
@@ -780,13 +1332,13 @@ var SmartAction = class _SmartAction {
     return this.#locator.all();
   }
   async evaluate(pageFunction, arg) {
-    return this.#locator.evaluate(pageFunction, arg);
+    return this.#safeAction("evaluate", pageFunction, arg);
   }
   async evaluateAll(pageFunction, arg) {
     return this.#locator.evaluateAll(pageFunction, arg);
   }
   async evaluateHandle(pageFunction, arg) {
-    return this.#locator.evaluateHandle(pageFunction, arg);
+    return this.#safeAction("evaluateHandle", pageFunction, arg);
   }
   first() {
     return this.#locator.first();
@@ -832,14 +1384,15 @@ var SmartAction = class _SmartAction {
     }
   }
   async getClasses() {
-    const cls = await this.#locator.getAttribute("class");
+    const cls = await this.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(
+    return this.#safeAction(
+      "evaluate",
       (el, prop) => window.getComputedStyle(el).getPropertyValue(prop),
       property
     );
@@ -858,12 +1411,21 @@ function clearAllCaches() {
   clearDiskCache();
 }
 function createSmartLocator(page, options = {}) {
-  const { verbose = false } = options;
+  const { verbose = false, actionTimeout = 1e4 } = 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);
   }
+  function withTimeout(promise, ms, label) {
+    if (!ms) return promise;
+    return Promise.race([
+      promise,
+      new Promise(
+        (_, reject) => setTimeout(() => reject(new Error(`Timeout: "${label}" exceeded ${ms}ms`)), ms)
+      )
+    ]);
+  }
   return {
     async prefetch(...queries) {
       const t0 = Date.now();
@@ -876,93 +1438,93 @@ function createSmartLocator(page, options = {}) {
     },
     async click(query, clickOptions) {
       const el = await resolve(query, "click");
-      await el.click(clickOptions);
+      await withTimeout(el.click(clickOptions), actionTimeout, `click("${query}")`);
       return el;
     },
     async dblclick(query, clickOptions) {
       const el = await resolve(query, "click");
-      await el.dblclick(clickOptions);
+      await withTimeout(el.dblclick(clickOptions), actionTimeout, `dblclick("${query}")`);
       return el;
     },
     async fill(query, value, fillOptions) {
       const el = await resolve(query, "fill");
-      await el.fill(value, fillOptions);
+      await withTimeout(el.fill(value, fillOptions), actionTimeout, `fill("${query}")`);
       return el;
     },
     async type(query, text, typeOptions) {
       const el = await resolve(query, "fill");
-      await el.type(text, typeOptions);
+      await withTimeout(el.type(text, typeOptions), actionTimeout, `type("${query}")`);
       return el;
     },
     async pressSequentially(query, text, pressOptions) {
       const el = await resolve(query, "fill");
-      await el.pressSequentially(text, pressOptions);
+      await withTimeout(el.pressSequentially(text, pressOptions), actionTimeout, `pressSequentially("${query}")`);
       return el;
     },
     async clear(query) {
       const el = await resolve(query, "fill");
-      await el.clear();
+      await withTimeout(el.clear(), actionTimeout, `clear("${query}")`);
       return el;
     },
     async press(query, key, pressOptions) {
       const el = await resolve(query, "fill");
-      await el.press(key, pressOptions);
+      await withTimeout(el.press(key, pressOptions), actionTimeout, `press("${query}")`);
       return el;
     },
     async check(query, checkOptions) {
       const el = await resolve(query, "check");
-      await el.check(checkOptions);
+      await withTimeout(el.check(checkOptions), actionTimeout, `check("${query}")`);
       return el;
     },
     async uncheck(query, uncheckOptions) {
       const el = await resolve(query, "uncheck");
-      await el.uncheck(uncheckOptions);
+      await withTimeout(el.uncheck(uncheckOptions), actionTimeout, `uncheck("${query}")`);
       return el;
     },
     async setChecked(query, checked, checkOptions) {
       const el = await resolve(query, checked ? "check" : "uncheck");
-      await el.setChecked(checked, checkOptions);
+      await withTimeout(el.setChecked(checked, checkOptions), actionTimeout, `setChecked("${query}")`);
       return el;
     },
     async select(query, values, selectOptions) {
       const el = await resolve(query, "select");
-      await el.selectOption(values, selectOptions);
+      await withTimeout(el.selectOption(values, selectOptions), actionTimeout, `select("${query}")`);
       return el;
     },
     async hover(query, hoverOptions) {
       const el = await resolve(query, "hover");
-      await el.hover(hoverOptions);
+      await withTimeout(el.hover(hoverOptions), actionTimeout, `hover("${query}")`);
       return el;
     },
     async focus(query) {
       const el = await resolve(query, "click");
-      await el.focus();
+      await withTimeout(el.focus(), actionTimeout, `focus("${query}")`);
       return el;
     },
     async tap(query, tapOptions) {
       const el = await resolve(query, "click");
-      await el.tap(tapOptions);
+      await withTimeout(el.tap(tapOptions), actionTimeout, `tap("${query}")`);
       return el;
     },
     async setInputFiles(query, files, fileOptions) {
       const el = await resolve(query, "fill");
-      await el.setInputFiles(files, fileOptions);
+      await withTimeout(el.setInputFiles(files, fileOptions), actionTimeout, `setInputFiles("${query}")`);
       return el;
     },
     async dragTo(srcQuery, destQuery, dragOptions) {
       const src = await resolve(srcQuery, "click");
       const dest = await resolve(destQuery, "click");
-      await src.dragTo(dest, dragOptions);
+      await withTimeout(src.dragTo(dest, dragOptions), actionTimeout, `dragTo("${srcQuery}")`);
       return { source: src, target: dest };
     },
     async selectText(query) {
       const el = await resolve(query, "click");
-      await el.selectText();
+      await withTimeout(el.selectText(), actionTimeout, `selectText("${query}")`);
       return el;
     },
     async scrollIntoView(query) {
       const el = await resolve(query, null);
-      await el.scrollIntoViewIfNeeded();
+      await withTimeout(el.scrollIntoViewIfNeeded(), actionTimeout, `scrollIntoView("${query}")`);
       return el;
     },
     async screenshot(query, screenshotOptions) {
@@ -1049,8 +1611,11 @@ function createSmartLocator(page, options = {}) {
     },
     async exists(query) {
       try {
-        const el = await resolve(query, null);
-        return await el.exists();
+        const result = await resolveLocator(page, query, { ...options, action: null });
+        if (!result.found || result.confidence < 0.7) return false;
+        const { createPlaywrightLocator: createPlaywrightLocator2 } = await Promise.resolve().then(() => (init_parser(), parser_exports));
+        const locator = createPlaywrightLocator2(page, result.locatorString, result.isInFrame, result.frameSelector);
+        return await locator.count() > 0;
       } catch {
         return false;
       }