@testnexus/locatai 1.7.0

package/dist/index.mjs

@@ -0,0 +1,1145 @@
+// src/locatai.ts
+import path2 from "path";
+
+// src/providers/openai.ts
+import OpenAI from "openai";
+
+// src/providers/types.ts
+function cleanJson(raw) {
+  let s = raw.replace(/^```(?:json)?\s*/gm, "").replace(/```\s*$/gm, "").trim();
+  s = s.replace(/^(\s*)\/\/.*$/gm, "$1");
+  s = s.replace(/\/\*[\s\S]*?\*\//g, "");
+  s = s.replace(/,\s*([}\]])/g, "$1");
+  try {
+    JSON.parse(s);
+    return s;
+  } catch {
+  }
+  const jsonStart = s.search(/[{\[]/);
+  if (jsonStart >= 0) {
+    s = s.slice(jsonStart);
+    const openChar = s[0];
+    const closeChar = openChar === "{" ? "}" : "]";
+    let depth = 0;
+    let inString = false;
+    let escaped = false;
+    for (let i = 0; i < s.length; i++) {
+      const ch = s[i];
+      if (escaped) {
+        escaped = false;
+        continue;
+      }
+      if (ch === "\\") {
+        escaped = true;
+        continue;
+      }
+      if (ch === '"') {
+        inString = !inString;
+        continue;
+      }
+      if (inString) continue;
+      if (ch === openChar) depth++;
+      else if (ch === closeChar) {
+        depth--;
+        if (depth === 0) {
+          s = s.slice(0, i + 1);
+          break;
+        }
+      }
+    }
+  }
+  s = s.replace(/(?<="[^"]*?)\n(?=[^"]*?")/g, "\\n");
+  s = s.replace(/(?<="[^"]*?)\t(?=[^"]*?")/g, "\\t");
+  s = s.replace(/,\s*([}\]])/g, "$1");
+  return s.trim();
+}
+var DEFAULT_MODELS = {
+  openai: "gpt-5-nano",
+  gpt: "gpt-5-nano",
+  anthropic: "claude-sonnet-4-20250514",
+  claude: "claude-sonnet-4-20250514",
+  google: "gemini-2.5-flash",
+  gemini: "gemini-2.5-flash",
+  local: "gemma3:4b",
+  ollama: "gemma3:4b"
+};
+
+// src/types.ts
+import { z } from "zod";
+var Strategy = z.object({
+  type: z.enum(["testid", "role", "label", "placeholder", "text", "altText", "title", "css"]),
+  value: z.string().nullable().optional(),
+  selector: z.string().nullable().optional(),
+  role: z.string().nullable().optional(),
+  name: z.string().nullable().optional(),
+  text: z.string().nullable().optional(),
+  exact: z.boolean().nullable().optional()
+});
+var LocatAIPlan = z.object({
+  candidates: z.array(z.object({
+    strategy: Strategy,
+    confidence: z.number(),
+    why: z.string()
+  }))
+});
+var LocatAIError = class _LocatAIError extends Error {
+  constructor(message, context) {
+    const detailedMessage = _LocatAIError.formatMessage(message, context);
+    super(detailedMessage);
+    this.name = "LocatAIError";
+    this.context = context;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _LocatAIError);
+    }
+  }
+  static formatMessage(message, ctx) {
+    const lines = [
+      `
+\u256D\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256E`,
+      `\u2502  \u{1F50D} LOCATAI: Element Not Found                          \u2502`,
+      `\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256F`,
+      ``,
+      `  \u274C ${message}`,
+      ``,
+      `  \u{1F4CB} Context:`,
+      `     \u2022 Action: ${ctx.action.toUpperCase()}`,
+      `     \u2022 Looking for: "${ctx.contextName}"`,
+      `     \u2022 Page URL: ${ctx.url}`,
+      `     \u2022 Candidates analyzed: ${ctx.candidatesAnalyzed}`
+    ];
+    if (ctx.originalError) {
+      lines.push(`     \u2022 Original error: ${ctx.originalError}`);
+    }
+    if (ctx.strategiesTried.length > 0) {
+      lines.push(``, `  \u{1F52C} Strategies tried:`);
+      ctx.strategiesTried.forEach((s, i) => {
+        lines.push(`     ${i + 1}. [${s.type}] \u2192 ${s.reason}`);
+      });
+    } else {
+      lines.push(``, `  \u26A0\uFE0F  No strategies were returned by AI`);
+    }
+    lines.push(
+      ``,
+      `  \u{1F4A1} Tips:`,
+      `     \u2022 Make sure the element exists on the page`,
+      `     \u2022 Try a more specific description`,
+      `     \u2022 Check if the element is visible and not hidden`,
+      ``
+    );
+    return lines.join("\n");
+  }
+};
+var locatAIPlanJsonSchema = {
+  type: "object",
+  properties: {
+    candidates: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          strategy: {
+            type: "object",
+            properties: {
+              type: { type: "string", enum: ["testid", "role", "label", "placeholder", "text", "altText", "title", "css"] },
+              value: { type: ["string", "null"] },
+              selector: { type: ["string", "null"] },
+              role: { type: ["string", "null"] },
+              name: { type: ["string", "null"] },
+              text: { type: ["string", "null"] },
+              exact: { type: ["boolean", "null"] }
+            },
+            required: ["type", "value", "selector", "role", "name", "text", "exact"],
+            additionalProperties: false
+          },
+          confidence: { type: "number" },
+          why: { type: "string" }
+        },
+        required: ["strategy", "confidence", "why"],
+        additionalProperties: false
+      },
+      maxItems: 3
+    }
+  },
+  required: ["candidates"],
+  additionalProperties: false
+};
+
+// src/logger.ts
+var c = {
+  reset: "\x1B[0m",
+  bold: "\x1B[1m",
+  dim: "\x1B[2m",
+  italic: "\x1B[3m",
+  gray: "\x1B[90m",
+  red: "\x1B[91m",
+  green: "\x1B[92m",
+  yellow: "\x1B[93m",
+  blue: "\x1B[94m",
+  purple: "\x1B[95m",
+  cyan: "\x1B[96m",
+  white: "\x1B[97m",
+  bgPurple: "\x1B[48;5;99m",
+  bgGreen: "\x1B[48;5;28m",
+  bgRed: "\x1B[48;5;124m",
+  bgBlue: "\x1B[48;5;24m"
+};
+function formatStrategy(s) {
+  switch (s.type) {
+    case "testid":
+      return `getByTestId("${s.value}")`;
+    case "role":
+      return `getByRole("${s.role}"${s.name ? `, { name: "${s.name}" }` : ""})`;
+    case "label":
+      return `getByLabel("${s.text}")`;
+    case "placeholder":
+      return `getByPlaceholder("${s.text}")`;
+    case "text":
+      return `getByText("${s.text}")`;
+    case "css":
+      return `locator("${s.selector}")`;
+    default:
+      return JSON.stringify(s);
+  }
+}
+var locataiLog = {
+  banner: () => {
+    console.log();
+    console.log(`${c.bgPurple}${c.bold}${c.white}  \u2726 LocatAI  ${c.reset}`);
+  },
+  actionFailed: (action, contextName) => {
+    console.log(`${c.gray}  \u2502${c.reset}`);
+    console.log(`${c.gray}  \u251C\u2500${c.reset} ${c.yellow}\u26A1${c.reset} ${c.dim}${action.toUpperCase()}${c.reset} ${c.white}${contextName}${c.reset}`);
+  },
+  askingAI: (_contextName, candidateCount, totalCollected) => {
+    const filtered = totalCollected && totalCollected > candidateCount ? ` ${c.dim}(filtered from ${totalCollected})${c.reset}` : "";
+    console.log(`${c.gray}  \u2502  ${c.purple}\u2B21${c.reset} ${c.dim}analyzing ${candidateCount} elements...${c.reset}${filtered}`);
+  },
+  aiResponse: (length) => {
+    console.log(`${c.gray}  \u2502  ${c.dim}\u21B3 received ${length} chars${c.reset}`);
+  },
+  candidateRejected: (type, reason) => {
+    console.log(`${c.gray}  \u2502  ${c.dim}\u21B3 [${type}] skipped: ${reason}${c.reset}`);
+  },
+  candidateError: (type, error) => {
+    console.log(`${c.gray}  \u2502  ${c.red}\u21B3 [${type}] error: ${error}${c.reset}`);
+  },
+  healed: (contextName, strategy) => {
+    const strategyStr = formatStrategy(strategy);
+    console.log(`${c.gray}  \u2502${c.reset}`);
+    console.log(`${c.gray}  \u251C\u2500${c.reset} ${c.green}\u2713${c.reset} ${c.bold}${c.white}${contextName}${c.reset}`);
+    console.log(`${c.gray}  \u2502  ${c.dim}\u2192 ${strategyStr}${c.reset}`);
+  },
+  tokenUsage: (input, output, total) => {
+    console.log(`${c.gray}  \u2502  ${c.dim}\u2191 ${c.cyan}${input}${c.dim} input \xB7 ${c.cyan}${output}${c.dim} output \xB7 ${c.bold}${c.cyan}${total}${c.dim} total tokens${c.reset}`);
+    console.log(`${c.gray}  \u2514${"\u2500".repeat(49)}${c.reset}`);
+    console.log();
+  },
+  usedCache: (contextName) => {
+    console.log(`${c.gray}  \u2502  ${c.cyan}\u25C6${c.reset} ${c.dim}cached: ${contextName}${c.reset}`);
+    console.log(`${c.gray}  \u2514${"\u2500".repeat(49)}${c.reset}`);
+    console.log();
+  },
+  cacheMiss: (contextName) => {
+    console.log(`${c.gray}  \u2502  ${c.yellow}\u25CB${c.reset} ${c.dim}cache stale for "${contextName}", re-healing...${c.reset}`);
+  },
+  healFailed: (contextName, error) => {
+    console.log(`${c.gray}  \u2502${c.reset}`);
+    console.log(`${c.gray}  \u251C\u2500${c.reset} ${c.red}\u2715${c.reset} ${c.red}${contextName}${c.reset}`);
+    console.log(`${c.gray}  \u2502  ${c.dim}${error}${c.reset}`);
+    console.log(`${c.gray}  \u2514${"\u2500".repeat(49)}${c.reset}`);
+    console.log();
+  },
+  aiDetectMode: (_action, contextName) => {
+    console.log(`${c.gray}  \u2502${c.reset}`);
+    console.log(`${c.gray}  \u251C\u2500${c.reset} ${c.purple}\u25C8${c.reset} ${c.dim}AI DETECT${c.reset} ${c.white}${contextName}${c.reset}`);
+  },
+  noValidCandidate: (contextName) => {
+    console.log(`${c.gray}  \u2502  ${c.red}\u21B3 no valid candidate found for "${contextName}"${c.reset}`);
+  },
+  warn: (message) => {
+    console.log(`${c.gray}  \u2502${c.reset}`);
+    console.log(`${c.gray}  \u251C\u2500${c.reset} ${c.yellow}\u26A0${c.reset} ${c.yellow}${message}${c.reset}`);
+    console.log(`${c.gray}  \u2514${"\u2500".repeat(49)}${c.reset}`);
+  },
+  aiDisabled: () => {
+    console.log(`${c.yellow}\u26A0 Set SELF_HEAL=1 or AI_SELF_HEAL=true with AI_API_KEY to enable AI detection${c.reset}`);
+  },
+  nativeFallback: (action, contextName) => {
+    console.log(`${c.dim}  \u21B3 AI healing disabled \u2014 running native Playwright ${action} for "${contextName}"${c.reset}`);
+  }
+};
+
+// src/providers/openai.ts
+var OpenAIProvider = class {
+  constructor(config) {
+    this.name = "openai";
+    this.client = new OpenAI({ apiKey: config.apiKey });
+    this.model = config.model ?? DEFAULT_MODELS.openai;
+  }
+  async generateLocatAIPlan(input) {
+    try {
+      const resp = await this.client.responses.create({
+        model: this.model,
+        input: [
+          { role: "system", content: input.systemPrompt },
+          { role: "user", content: input.userContent }
+        ],
+        text: {
+          format: {
+            type: "json_schema",
+            name: "LocatAIPlan",
+            strict: true,
+            schema: input.jsonSchema
+          }
+        },
+        store: false,
+        reasoning: { "effort": "low" }
+      });
+      const content = resp.output_text;
+      locataiLog.aiResponse(content?.length ?? 0);
+      const usage = resp.usage;
+      const tokenUsage = usage ? {
+        inputTokens: usage.input_tokens ?? usage.prompt_tokens ?? 0,
+        outputTokens: usage.output_tokens ?? usage.completion_tokens ?? 0,
+        totalTokens: (usage.input_tokens ?? usage.prompt_tokens ?? 0) + (usage.output_tokens ?? usage.completion_tokens ?? 0)
+      } : null;
+      if (!content) return { plan: null, tokenUsage };
+      try {
+        return { plan: LocatAIPlan.parse(JSON.parse(cleanJson(content))), tokenUsage };
+      } catch (parseErr) {
+        locataiLog.candidateError("parse", `Failed to parse AI response: ${parseErr?.message ?? ""}`);
+        return { plan: null, tokenUsage };
+      }
+    } catch (aiErr) {
+      locataiLog.candidateError("api", aiErr?.message ?? String(aiErr));
+      throw aiErr;
+    }
+  }
+};
+
+// src/providers/anthropic.ts
+import Anthropic from "@anthropic-ai/sdk";
+var AnthropicProvider = class {
+  constructor(config) {
+    this.name = "anthropic";
+    this.client = new Anthropic({ apiKey: config.apiKey });
+    this.model = config.model ?? DEFAULT_MODELS.anthropic;
+  }
+  async generateLocatAIPlan(input) {
+    try {
+      const resp = await this.client.messages.create({
+        model: this.model,
+        max_tokens: 4096,
+        system: input.systemPrompt,
+        messages: [
+          { role: "user", content: input.userContent }
+        ]
+      }, {
+        headers: {
+          "anthropic-beta": "structured-outputs-2025-11-13"
+        }
+      });
+      const content = resp.structured_output ?? resp.content?.[0]?.text;
+      locataiLog.aiResponse(typeof content === "string" ? content.length : JSON.stringify(content).length);
+      const usage = resp.usage;
+      const tokenUsage = usage ? {
+        inputTokens: usage.input_tokens ?? 0,
+        outputTokens: usage.output_tokens ?? 0,
+        totalTokens: (usage.input_tokens ?? 0) + (usage.output_tokens ?? 0)
+      } : null;
+      if (!content) return { plan: null, tokenUsage };
+      try {
+        const raw = typeof content === "string" ? content : JSON.stringify(content);
+        return { plan: LocatAIPlan.parse(JSON.parse(cleanJson(raw))), tokenUsage };
+      } catch (parseErr) {
+        locataiLog.candidateError("parse", `Failed to parse AI response: ${parseErr?.message ?? ""}`);
+        return { plan: null, tokenUsage };
+      }
+    } catch (aiErr) {
+      locataiLog.candidateError("api", aiErr?.message ?? String(aiErr));
+      throw aiErr;
+    }
+  }
+};
+
+// src/providers/google.ts
+import { GoogleGenAI } from "@google/genai";
+var GoogleProvider = class {
+  constructor(config) {
+    this.name = "google";
+    this.ai = new GoogleGenAI({ apiKey: config.apiKey });
+    this.model = config.model ?? DEFAULT_MODELS.google;
+  }
+  async generateLocatAIPlan(input) {
+    try {
+      const combinedPrompt = `${input.systemPrompt}
+
+---
+
+${input.userContent}
+
+Respond with valid JSON matching this schema:
+${JSON.stringify(input.jsonSchema, null, 2)}`;
+      const response = await this.ai.models.generateContent({
+        model: this.model,
+        contents: combinedPrompt,
+        config: {
+          responseMimeType: "application/json"
+        }
+      });
+      const content = response.text;
+      locataiLog.aiResponse(content?.length ?? 0);
+      const usage = response.usageMetadata;
+      const tokenUsage = usage ? {
+        inputTokens: usage.promptTokenCount ?? 0,
+        outputTokens: usage.candidatesTokenCount ?? 0,
+        totalTokens: (usage.promptTokenCount ?? 0) + (usage.candidatesTokenCount ?? 0)
+      } : null;
+      if (!content) return { plan: null, tokenUsage };
+      try {
+        return { plan: LocatAIPlan.parse(JSON.parse(cleanJson(content))), tokenUsage };
+      } catch (parseErr) {
+        locataiLog.candidateError("parse", `Failed to parse AI response: ${parseErr?.message ?? ""}`);
+        return { plan: null, tokenUsage };
+      }
+    } catch (aiErr) {
+      locataiLog.candidateError("api", aiErr?.message ?? String(aiErr));
+      throw aiErr;
+    }
+  }
+};
+
+// src/providers/local.ts
+import { Ollama } from "ollama";
+function normalizeResponse(raw) {
+  if (!raw || typeof raw !== "object") return raw;
+  if (Array.isArray(raw.candidates) && raw.candidates.length > 0 && raw.candidates[0].strategy) {
+    return raw;
+  }
+  if (Array.isArray(raw.candidates)) {
+    raw.candidates = raw.candidates.map((c2) => {
+      if (c2.strategy) return c2;
+      const strategyFields = ["type", "value", "selector", "role", "name", "text", "exact"];
+      const strategy = {};
+      const rest = {};
+      for (const [k, v] of Object.entries(c2)) {
+        if (strategyFields.includes(k)) strategy[k] = v;
+        else rest[k] = v;
+      }
+      if (strategy.type) {
+        return { strategy, ...rest };
+      }
+      return c2;
+    });
+    return raw;
+  }
+  if (raw.type && (raw.confidence !== void 0 || raw.why)) {
+    const strategyFields = ["type", "value", "selector", "role", "name", "text", "exact"];
+    const strategy = {};
+    const rest = {};
+    for (const [k, v] of Object.entries(raw)) {
+      if (strategyFields.includes(k)) strategy[k] = v;
+      else rest[k] = v;
+    }
+    return { candidates: [{ strategy, ...rest }] };
+  }
+  for (const wrapper of ["result", "response", "data", "output"]) {
+    if (raw[wrapper]) return normalizeResponse(raw[wrapper]);
+  }
+  return raw;
+}
+var LocalProvider = class {
+  constructor(config) {
+    this.name = "local";
+    const host = config.apiKey || process.env.OLLAMA_HOST || "http://127.0.0.1:11434";
+    this.client = new Ollama({ host });
+    this.model = config.model ?? DEFAULT_MODELS.local;
+  }
+  async generateLocatAIPlan(input) {
+    try {
+      const formatSchema = input.jsonSchema ?? "json";
+      const resp = await this.client.chat({
+        model: this.model,
+        messages: [
+          { role: "system", content: input.systemPrompt },
+          { role: "user", content: input.userContent }
+        ],
+        format: formatSchema,
+        stream: false,
+        think: false,
+        options: { temperature: 0 }
+      });
+      const content = resp.message?.content;
+      locataiLog.aiResponse(content?.length ?? 0);
+      const tokenUsage = resp.prompt_eval_count != null ? {
+        inputTokens: resp.prompt_eval_count ?? 0,
+        outputTokens: resp.eval_count ?? 0,
+        totalTokens: (resp.prompt_eval_count ?? 0) + (resp.eval_count ?? 0)
+      } : null;
+      if (!content) return { plan: null, tokenUsage };
+      try {
+        const parsed = JSON.parse(cleanJson(content));
+        const normalized = normalizeResponse(parsed);
+        return { plan: LocatAIPlan.parse(normalized), tokenUsage };
+      } catch (parseErr) {
+        locataiLog.candidateError("parse", `Failed to parse AI response: ${parseErr?.message ?? ""}`);
+        return { plan: null, tokenUsage };
+      }
+    } catch (aiErr) {
+      locataiLog.candidateError("api", aiErr?.message ?? String(aiErr));
+      throw aiErr;
+    }
+  }
+};
+
+// src/providers/index.ts
+function createAIProvider(providerName, config) {
+  switch (providerName) {
+    case "openai":
+    case "gpt":
+      return new OpenAIProvider(config);
+    case "anthropic":
+    case "claude":
+      return new AnthropicProvider(config);
+    case "google":
+    case "gemini":
+      return new GoogleProvider(config);
+    case "local":
+    case "ollama":
+      return new LocalProvider(config);
+    default:
+      throw new Error(`Unknown AI provider: ${providerName}. Supported: openai/gpt, anthropic/claude, google/gemini, local/ollama`);
+  }
+}
+
+// src/utils.ts
+import fs from "fs/promises";
+import path from "path";
+function isValidLocator(target) {
+  return typeof target !== "string" || target !== "";
+}
+function buildLocator(page, s) {
+  switch (s.type) {
+    case "testid": {
+      if (!s.value) throw new Error("testid strategy requires 'value'");
+      const v = s.value.replace(/"/g, '\\"');
+      return page.locator(
+        `[data-testid="${v}"],[data-test="${v}"],[data-test-id="${v}"],[data-qa="${v}"],[data-cy="${v}"]`
+      );
+    }
+    case "role":
+      if (!s.role) throw new Error("role strategy requires 'role'");
+      return page.getByRole(s.role, { name: s.name ?? void 0, exact: s.exact ?? true });
+    case "label":
+      if (!s.text) throw new Error("label strategy requires 'text'");
+      return page.getByLabel(s.text, { exact: s.exact ?? void 0 });
+    case "placeholder":
+      if (!s.text) throw new Error("placeholder strategy requires 'text'");
+      return page.getByPlaceholder(s.text, { exact: s.exact ?? void 0 });
+    case "text":
+      if (!s.text) throw new Error("text strategy requires 'text'");
+      return page.getByText(s.text, { exact: s.exact ?? void 0 });
+    case "altText":
+      if (!s.text) throw new Error("altText strategy requires 'text'");
+      return page.getByAltText(s.text, { exact: s.exact ?? void 0 });
+    case "title":
+      if (!s.text) throw new Error("title strategy requires 'text'");
+      return page.getByTitle(s.text, { exact: s.exact ?? void 0 });
+    case "css":
+      if (!s.selector) throw new Error("css strategy requires 'selector'");
+      return page.locator(s.selector);
+  }
+  throw new Error(`Unknown strategy type: ${s.type}`);
+}
+function validateStrategy(s) {
+  switch (s.type) {
+    case "testid":
+      if (!s.value) return "missing 'value'";
+      break;
+    case "role":
+      if (!s.role) return "missing 'role'";
+      break;
+    case "label":
+    case "placeholder":
+    case "text":
+    case "altText":
+    case "title":
+      if (!s.text) return "missing 'text'";
+      break;
+    case "css":
+      if (!s.selector) return "missing 'selector'";
+      break;
+  }
+  return null;
+}
+async function waitForReady(loc, _action, timeout) {
+  await loc.waitFor({ state: "visible", timeout });
+}
+async function waitForStable(page) {
+  await page.waitForLoadState("domcontentloaded");
+}
+async function collectCandidates(page, action, limit = 80) {
+  const selector = action === "click" || action === "dblclick" || action === "hover" ? [
+    // Native interactive elements
+    "button",
+    "a",
+    "label",
+    "summary",
+    "img",
+    // Input types that are clickable
+    "input[type='button']",
+    "input[type='submit']",
+    "input[type='reset']",
+    "input[type='checkbox']",
+    "input[type='radio']",
+    "input[type='image']",
+    "input[type='file']",
+    // Dropdowns and list items
+    "select",
+    "option",
+    "li",
+    // ARIA widget roles
+    "[role='button']",
+    "[role='link']",
+    "[role='menuitem']",
+    "[role='menuitemcheckbox']",
+    "[role='menuitemradio']",
+    "[role='tab']",
+    "[role='switch']",
+    "[role='option']",
+    "[role='checkbox']",
+    "[role='radio']",
+    "[role='combobox']",
+    "[role='slider']",
+    "[role='spinbutton']",
+    // ARIA structural roles that are often clickable
+    "[role='treeitem']",
+    "[role='gridcell']",
+    "[role='row']",
+    // Event-based and focusable
+    "[onclick]",
+    "[ondblclick]",
+    "[onmouseenter]",
+    "[onmouseover]",
+    "[tabindex]:not([tabindex='-1'])",
+    // Test-targeted elements
+    "[data-testid]",
+    "[data-test]",
+    "[data-test-id]",
+    "[data-qa]",
+    "[data-cy]"
+  ].join(",") : action === "selectOption" ? "select,[role='combobox'],[role='listbox'],option,[role='option'],[data-testid]" : "input,textarea,[contenteditable='true'],[role='textbox'],select,[role='combobox'],[data-testid]";
+  return page.evaluate(({ selector: selector2, limit: limit2 }) => {
+    const els = Array.from(document.querySelectorAll(selector2)).slice(0, limit2);
+    const pickTest = (el) => {
+      for (const a of ["data-testid", "data-test", "data-test-id", "data-qa", "data-cy"]) {
+        const v = el.getAttribute(a);
+        if (v) return v;
+      }
+      return null;
+    };
+    const isVisible = (el) => {
+      const e = el;
+      const s = window.getComputedStyle(e);
+      if (s.display === "none" || s.visibility === "hidden") return false;
+      const r = e.getBoundingClientRect();
+      return r.width > 0 && r.height > 0;
+    };
+    const norm = (t) => t.replace(/\s+/g, " ").trim().slice(0, 60);
+    const result = [];
+    for (const el of els) {
+      const vis = isVisible(el);
+      const o = { tag: el.tagName.toLowerCase() };
+      if (!vis) o.hid = true;
+      const role = el.getAttribute("role");
+      if (role) o.role = role;
+      const aria = el.getAttribute("aria-label");
+      if (aria) o.aria = aria;
+      const name = el.getAttribute("name");
+      if (name) o.name = name;
+      const ph = el.getAttribute("placeholder");
+      if (ph) o.ph = ph;
+      const type = el.getAttribute("type");
+      if (type) o.type = type;
+      const href = el.getAttribute("href");
+      if (href) o.href = href;
+      const alt = el.getAttribute("alt");
+      if (alt) o.alt = alt;
+      const title = el.getAttribute("title");
+      if (title) o.title = title;
+      const forAttr = el.getAttribute("for");
+      if (forAttr) o.for = forAttr;
+      const id = el.id;
+      if (id) o.id = id;
+      const cls = el.className;
+      if (cls && typeof cls === "string") o.cls = cls.slice(0, 60);
+      const tid = pickTest(el);
+      if (tid) o.tid = tid;
+      const text = norm(el.innerText || el.textContent || "");
+      if (text) o.txt = text;
+      result.push(o);
+    }
+    return result;
+  }, { selector, limit });
+}
+function rankCandidates(candidates, contextName, limit) {
+  if (candidates.length <= limit) return candidates;
+  const ctx = contextName.toLowerCase();
+  const stopWords = /* @__PURE__ */ new Set(["the", "for", "and", "with", "that", "this", "from", "into", "field", "element"]);
+  const ctxWords = ctx.split(/\W+/).filter((w) => w.length >= 3 && !stopWords.has(w));
+  const inferTag = (c2) => {
+    if (/\b(button|btn|submit|reset|click)\b/i.test(c2)) return ["button", "input"];
+    if (/\b(link|anchor|nav)\b/i.test(c2)) return ["a"];
+    if (/\b(input|text|email|password|search|phone|tel|url|number|name)\b/i.test(c2)) return ["input", "textarea"];
+    if (/\b(checkbox|check|agree|subscribe|toggle)\b/i.test(c2)) return ["input", "label"];
+    if (/\b(radio)\b/i.test(c2)) return ["input"];
+    if (/\b(select|dropdown|combo)\b/i.test(c2)) return ["select"];
+    if (/\b(textarea|comment)\b/i.test(c2)) return ["textarea"];
+    if (/\b(image|img|icon|logo)\b/i.test(c2)) return ["img"];
+    if (/\b(label)\b/i.test(c2)) return ["label"];
+    if (/\b(list item|li)\b/i.test(c2)) return ["li"];
+    return [];
+  };
+  const expectedTags = inferTag(contextName);
+  const textFields = (cand) => {
+    const fields = [];
+    for (const key of ["aria", "txt", "ph", "name", "tid", "alt", "title", "id", "for", "role"]) {
+      const v = cand[key];
+      if (typeof v === "string" && v) fields.push(v.toLowerCase());
+    }
+    return fields;
+  };
+  const scored = candidates.map((cand, idx) => {
+    let score = 0;
+    const texts = textFields(cand);
+    const allText = texts.join(" ");
+    if (texts.some((t) => t.includes(ctx))) score += 15;
+    for (const t of texts) {
+      if (ctx.includes(t) && t.length >= 3) {
+        score += 8;
+        break;
+      }
+    }
+    for (const word of ctxWords) {
+      if (allText.includes(word)) score += 3;
+    }
+    const tag = String(cand.tag ?? "").toLowerCase();
+    if (expectedTags.length > 0 && expectedTags.includes(tag)) score += 5;
+    const role = String(cand.role ?? "").toLowerCase();
+    if (role && ctx.includes(role)) score += 5;
+    if (cand.tid) score += 2;
+    if (!cand.hid) score += 1;
+    return { cand, score, idx };
+  });
+  scored.sort((a, b) => b.score - a.score || a.idx - b.idx);
+  return scored.slice(0, limit).map((s) => s.cand);
+}
+async function readJson(file, fallback) {
+  try {
+    return JSON.parse(await fs.readFile(file, "utf8"));
+  } catch {
+    return fallback;
+  }
+}
+async function writeAtomic(file, data) {
+  const dir = path.dirname(file);
+  try {
+    await fs.mkdir(dir, { recursive: true });
+  } catch {
+  }
+  const tmp = file + ".tmp";
+  await fs.writeFile(tmp, JSON.stringify(data, null, 2), "utf8");
+  await fs.rename(tmp, file);
+}
+async function appendLog(reportFile, entry) {
+  const dir = path.dirname(reportFile);
+  try {
+    await fs.mkdir(dir, { recursive: true });
+  } catch {
+  }
+  await fs.appendFile(reportFile, JSON.stringify(entry) + "\n", "utf8").catch(() => {
+  });
+}
+function cacheKey(page, action, contextName) {
+  const u = new URL(page.url());
+  return `${action}::${u.origin}${u.pathname}::${contextName}`;
+}
+function isRetryableError(err) {
+  const error = err;
+  const status = error?.status ?? error?.statusCode ?? error?.response?.status;
+  if (status === 429 || status !== void 0 && status >= 500) return true;
+  const code = error?.code;
+  if (code === "ECONNRESET" || code === "ETIMEDOUT" || code === "ENOTFOUND") return true;
+  const msg = String(error?.message ?? "").toLowerCase();
+  return msg.includes("rate limit") || msg.includes("timeout") || msg.includes("overloaded");
+}
+async function withRetry(fn, maxRetries = 1, baseDelayMs = 1e3) {
+  let lastError;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastError = err;
+      if (attempt < maxRetries && isRetryableError(err)) {
+        const delay = baseDelayMs * Math.pow(2, attempt);
+        await new Promise((resolve) => setTimeout(resolve, delay));
+      } else {
+        throw err;
+      }
+    }
+  }
+  throw lastError;
+}
+
+// src/locatai.ts
+var LOCATAI_SYMBOL = /* @__PURE__ */ Symbol.for("locatai");
+function withLocatAI(page, opts) {
+  if (page[LOCATAI_SYMBOL]) {
+    return page;
+  }
+  const enabled = opts?.enabled ?? (process.env.SELF_HEAL === "1" || process.env.AI_SELF_HEAL === "true");
+  const apiKey = opts?.apiKey ?? process.env.AI_API_KEY;
+  const providerName = opts?.provider ?? process.env.AI_PROVIDER?.toLowerCase() ?? "openai";
+  const model = opts?.model ?? process.env.AI_MODEL;
+  const isLocalProvider = providerName === "local" || providerName === "ollama";
+  let aiProvider = null;
+  if (enabled && (apiKey || isLocalProvider)) {
+    aiProvider = createAIProvider(providerName, {
+      apiKey: isLocalProvider ? process.env.OLLAMA_HOST ?? "" : apiKey ?? "",
+      model
+    });
+  }
+  const cacheFile = opts?.cacheFile ?? path2.join(process.cwd(), ".self-heal", "healed_locators.json");
+  const reportFile = opts?.reportFile ?? path2.join(process.cwd(), ".self-heal", "heal_events.jsonl");
+  const maxAiTries = opts?.maxAiTries ?? 4;
+  const maxCandidates = opts?.maxCandidates ?? 80;
+  const timeout = opts?.timeout ?? 5e3;
+  const quickTimeout = enabled ? 1e3 : timeout;
+  let currentTestName = opts?.testName;
+  let bannerShownForTest;
+  const mem = /* @__PURE__ */ new Map();
+  let diskCacheLoaded = false;
+  let diskCache = {};
+  async function ensureDiskCacheLoaded() {
+    if (!diskCacheLoaded) {
+      diskCache = await readJson(cacheFile, {});
+      diskCacheLoaded = true;
+    }
+    return diskCache;
+  }
+  function showBannerOnce() {
+    if (bannerShownForTest !== currentTestName) {
+      locataiLog.banner();
+      bannerShownForTest = currentTestName;
+    }
+  }
+  async function log(entry) {
+    await appendLog(reportFile, entry);
+  }
+  async function askAI(action, contextName) {
+    if (!aiProvider) throw new Error("Healing disabled or API key not set");
+    const allCandidates = await collectCandidates(page, action, maxCandidates);
+    const candidates = rankCandidates(allCandidates, contextName, Math.min(maxCandidates, 40));
+    locataiLog.askingAI(contextName, candidates.length, allCandidates.length);
+    const systemPrompt = [
+      "You are a Playwright locator expert. Given a list of candidate elements from the page, identify the one matching contextName.",
+      "Return up to 3 strategy alternatives. Prefer: testid > role+name > label > placeholder > text > altText > title > css.",
+      "Candidate keys: tag=tagName, tid=data-testid, aria=aria-label, ph=placeholder, txt=innerText, alt=alt, title=title, for=htmlFor, cls=className, hid=hidden. id/name/role/type/href as named.",
+      "Strategy types: testid(value=testid), role(role+name, exact optional), label(text), placeholder(text), text(text, exact optional), altText(text), title(text), css(selector). No XPath.",
+      "IMPORTANT: For label/placeholder/text/altText/title strategies, the 'text' field is REQUIRED and must be the actual text/label/placeholder value.",
+      "For testid strategy, the 'value' field is REQUIRED. For css, the 'selector' field is REQUIRED. For role, the 'role' field is REQUIRED.",
+      "Elements with hid:true may be CSS-hidden inputs (opacity:0) or offscreen \u2014 they are still valid targets if they match contextName."
+    ].join("\n");
+    const userContent = JSON.stringify({ url: page.url(), action, contextName, candidates });
+    const result = await withRetry(
+      () => aiProvider.generateLocatAIPlan({
+        systemPrompt,
+        userContent,
+        jsonSchema: locatAIPlanJsonSchema
+      }),
+      2,
+      // 2 retries (3 total attempts)
+      1e3
+    );
+    return { plan: result.plan, candidatesAnalyzed: candidates.length, tokenUsage: result.tokenUsage };
+  }
+  async function pickValid(plan, options) {
+    const strategiesTried = [];
+    const skipVisibilityCheck = options?.skipVisibilityCheck ?? false;
+    for (const c2 of plan.candidates.slice(0, maxAiTries)) {
+      const validationError = validateStrategy(c2.strategy);
+      if (validationError) {
+        locataiLog.candidateRejected(c2.strategy.type, validationError);
+        strategiesTried.push({ type: c2.strategy.type, reason: validationError });
+        continue;
+      }
+      try {
+        const loc = buildLocator(page, c2.strategy);
+        const count = await loc.count();
+        if (count !== 1) {
+          const reason = count === 0 ? "element not found" : `matched ${count} elements (must be unique)`;
+          locataiLog.candidateRejected(c2.strategy.type, `count=${count}`);
+          strategiesTried.push({ type: c2.strategy.type, reason });
+          continue;
+        }
+        if (!skipVisibilityCheck) {
+          const visible = await loc.first().isVisible();
+          if (!visible) {
+            locataiLog.candidateRejected(c2.strategy.type, "not visible");
+            strategiesTried.push({ type: c2.strategy.type, reason: "element exists but not visible" });
+            continue;
+          }
+        }
+        return { choice: c2, strategiesTried };
+      } catch (err) {
+        const reason = err?.message ?? "unknown error";
+        locataiLog.candidateError(c2.strategy.type, reason);
+        strategiesTried.push({ type: c2.strategy.type, reason: `error: ${reason}` });
+        continue;
+      }
+    }
+    return { choice: null, strategiesTried };
+  }
+  async function saveToCache(key, strategy, contextName) {
+    mem.set(key, strategy);
+    const cache = await ensureDiskCacheLoaded();
+    cache[key] = { ...strategy, context: contextName, testName: currentTestName };
+    await writeAtomic(cacheFile, cache);
+  }
+  async function locataiAction(action, target, contextName, performAction, options) {
+    const ts = (/* @__PURE__ */ new Date()).toISOString();
+    const key = cacheKey(page, action, contextName);
+    const aiOnlyMode = !isValidLocator(target);
+    let originalError = null;
+    if (!aiOnlyMode) {
+      try {
+        await waitForReady(target, action, quickTimeout);
+        await performAction(target);
+        return;
+      } catch (err) {
+        if (!enabled) throw err;
+        originalError = err;
+      }
+    }
+    if (!enabled && aiOnlyMode) {
+      locataiLog.nativeFallback(action, contextName);
+      const selector = typeof target === "string" ? target : "";
+      const nativeLoc = page.locator(selector);
+      await performAction(nativeLoc);
+      return;
+    }
+    showBannerOnce();
+    if (aiOnlyMode) {
+      locataiLog.aiDetectMode(action, contextName);
+    } else {
+      locataiLog.actionFailed(action, contextName);
+    }
+    const cache = await ensureDiskCacheLoaded();
+    const cached = mem.get(key) ?? cache[key];
+    if (cached) {
+      try {
+        const cachedLoc = buildLocator(page, cached);
+        await waitForReady(cachedLoc, action, timeout);
+        await performAction(cachedLoc);
+        if (action === "click" || action === "dblclick" || action === "selectOption") await waitForStable(page);
+        await log({ ts, url: page.url(), key, action, contextName, used: "cache", success: true, strategy: cached });
+        locataiLog.usedCache(contextName);
+        return;
+      } catch {
+        locataiLog.cacheMiss(contextName);
+      }
+    }
+    let candidatesAnalyzed = 0;
+    let strategiesTried = [];
+    let tokenUsage = null;
+    try {
+      const aiResult = await askAI(options?.aiAction ?? action, contextName);
+      candidatesAnalyzed = aiResult.candidatesAnalyzed;
+      tokenUsage = aiResult.tokenUsage;
+      if (!aiResult.plan) {
+        await log({ ts, url: page.url(), key, action, contextName, used: "healed", success: false, error: "AI returned no plan", tokenUsage });
+        locataiLog.noValidCandidate(contextName);
+        if (tokenUsage) locataiLog.tokenUsage(tokenUsage.inputTokens, tokenUsage.outputTokens, tokenUsage.totalTokens);
+        throw new LocatAIError("AI returned no suggestions", {
+          action,
+          contextName,
+          url: page.url(),
+          candidatesAnalyzed,
+          strategiesTried: [],
+          originalError: originalError?.message
+        });
+      }
+      const pickResult = await pickValid(aiResult.plan, { skipVisibilityCheck: options?.forceClick });
+      strategiesTried = pickResult.strategiesTried;
+      const choice = pickResult.choice;
+      if (!choice) {
+        await log({ ts, url: page.url(), key, action, contextName, used: "healed", success: false, error: "No valid candidate", tokenUsage });
+        locataiLog.noValidCandidate(contextName);
+        if (tokenUsage) locataiLog.tokenUsage(tokenUsage.inputTokens, tokenUsage.outputTokens, tokenUsage.totalTokens);
+        throw new LocatAIError("Could not find a matching element", {
+          action,
+          contextName,
+          url: page.url(),
+          candidatesAnalyzed,
+          strategiesTried,
+          originalError: originalError?.message
+        });
+      }
+      await saveToCache(key, choice.strategy, contextName);
+      const healedLoc = buildLocator(page, choice.strategy);
+      if (!options?.forceClick) {
+        await waitForReady(healedLoc, action, timeout);
+      }
+      await performAction(healedLoc);
+      if (action === "click" || action === "dblclick" || action === "selectOption") await waitForStable(page);
+      await log({
+        ts,
+        url: page.url(),
+        key,
+        action,
+        contextName,
+        used: "healed",
+        success: true,
+        confidence: choice.confidence,
+        why: choice.why,
+        strategy: choice.strategy,
+        tokenUsage
+      });
+      locataiLog.healed(contextName, choice.strategy);
+      if (tokenUsage) locataiLog.tokenUsage(tokenUsage.inputTokens, tokenUsage.outputTokens, tokenUsage.totalTokens);
+    } catch (healErr) {
+      if (healErr instanceof LocatAIError) {
+        await log({
+          ts,
+          url: page.url(),
+          key,
+          action,
+          contextName,
+          used: "healed",
+          success: false,
+          error: healErr.message
+        });
+        locataiLog.healFailed(contextName, "No matching element found");
+        throw healErr;
+      }
+      await log({
+        ts,
+        url: page.url(),
+        key,
+        action,
+        contextName,
+        used: "healed",
+        success: false,
+        error: `Heal failed: ${String(healErr?.message ?? healErr)}`
+      });
+      locataiLog.healFailed(contextName, String(healErr?.message ?? healErr));
+      throw new LocatAIError(String(healErr?.message ?? healErr), {
+        action,
+        contextName,
+        url: page.url(),
+        candidatesAnalyzed,
+        strategiesTried,
+        originalError: originalError?.message
+      });
+    }
+  }
+  const locataiMethods = {
+    click: (target, contextName, clickOptions) => locataiAction(
+      "click",
+      target,
+      contextName,
+      // For display:none elements (force mode), use dispatchEvent which bypasses
+      // the need for element dimensions. Regular click() fails on display:none.
+      clickOptions?.force ? (loc) => loc.dispatchEvent("click") : (loc) => loc.click({ timeout }),
+      { forceClick: clickOptions?.force }
+    ),
+    fill: (target, contextName, value) => locataiAction(
+      "fill",
+      target,
+      contextName,
+      (loc) => loc.fill(value, { timeout })
+    ),
+    selectOption: (target, contextName, value) => locataiAction(
+      "selectOption",
+      target,
+      contextName,
+      async (loc) => {
+        await loc.selectOption(value, { timeout });
+      }
+    ),
+    dblclick: (target, contextName) => locataiAction(
+      "dblclick",
+      target,
+      contextName,
+      (loc) => loc.dblclick({ timeout }),
+      { aiAction: "click" }
+      // Use click candidates for dblclick
+    ),
+    check: (target, contextName) => locataiAction(
+      "check",
+      target,
+      contextName,
+      (loc) => loc.check({ timeout }),
+      { aiAction: "fill" }
+      // Use fill candidates for check (inputs)
+    ),
+    uncheck: (target, contextName) => locataiAction(
+      "uncheck",
+      target,
+      contextName,
+      (loc) => loc.uncheck({ timeout }),
+      { aiAction: "fill" }
+      // Use fill candidates for uncheck (inputs)
+    ),
+    hover: (target, contextName) => locataiAction(
+      "hover",
+      target,
+      contextName,
+      (loc) => loc.hover({ timeout }),
+      { aiAction: "click" }
+      // Use click candidates for hover
+    ),
+    focus: (target, contextName) => locataiAction(
+      "focus",
+      target,
+      contextName,
+      (loc) => loc.focus({ timeout }),
+      { aiAction: "click" }
+      // Use click candidates — focusable elements include buttons, divs, etc.
+    ),
+    setTestName: (name) => {
+      currentTestName = name;
+    },
+    // Create a self-healing locator with semantic description fallback
+    locator: (selector, contextName) => {
+      const baseLoc = page.locator(selector);
+      return {
+        click: (options) => locataiMethods.click(baseLoc, contextName, options),
+        fill: (value) => locataiMethods.fill(baseLoc, contextName, value),
+        dblclick: () => locataiMethods.dblclick(baseLoc, contextName),
+        check: () => locataiMethods.check(baseLoc, contextName),
+        uncheck: () => locataiMethods.uncheck(baseLoc, contextName),
+        hover: () => locataiMethods.hover(baseLoc, contextName),
+        focus: () => locataiMethods.focus(baseLoc, contextName),
+        selectOption: (value) => locataiMethods.selectOption(baseLoc, contextName, value)
+      };
+    }
+  };
+  page[LOCATAI_SYMBOL] = true;
+  page.locatai = locataiMethods;
+  return page;
+}
+function createLocatAIFixture(opts) {
+  return {
+    page: async ({ page }, use) => {
+      const locataiPage = withLocatAI(page, opts);
+      await use(locataiPage);
+    }
+  };
+}
+export {
+  DEFAULT_MODELS,
+  LocatAIError,
+  createLocatAIFixture,
+  withLocatAI
+};