@qontinui/ui-bridge 0.1.1 → 0.3.0

package/dist/server/handlers.js

@@ -0,0 +1,4278 @@
+'use strict';
+
+// src/ai/fuzzy-matcher.ts
+var DEFAULT_FUZZY_CONFIG = {
+  threshold: 0.7,
+  levenshteinWeight: 0.3,
+  jaroWinklerWeight: 0.4,
+  ngramWeight: 0.3,
+  ngramSize: 2,
+  caseSensitive: false,
+  ignoreWhitespace: true
+};
+function levenshteinDistance(s1, s2) {
+  const len1 = s1.length;
+  const len2 = s2.length;
+  const matrix = Array(len1 + 1).fill(null).map(() => Array(len2 + 1).fill(0));
+  for (let i = 0; i <= len1; i++) matrix[i][0] = i;
+  for (let j = 0; j <= len2; j++) matrix[0][j] = j;
+  for (let i = 1; i <= len1; i++) {
+    for (let j = 1; j <= len2; j++) {
+      const cost = s1[i - 1] === s2[j - 1] ? 0 : 1;
+      matrix[i][j] = Math.min(
+        matrix[i - 1][j] + 1,
+        // deletion
+        matrix[i][j - 1] + 1,
+        // insertion
+        matrix[i - 1][j - 1] + cost
+        // substitution
+      );
+    }
+  }
+  return matrix[len1][len2];
+}
+function levenshteinSimilarity(s1, s2) {
+  if (s1.length === 0 && s2.length === 0) return 1;
+  if (s1.length === 0 || s2.length === 0) return 0;
+  const distance = levenshteinDistance(s1, s2);
+  const maxLength = Math.max(s1.length, s2.length);
+  return 1 - distance / maxLength;
+}
+function jaroSimilarity(s1, s2) {
+  if (s1.length === 0 && s2.length === 0) return 1;
+  if (s1.length === 0 || s2.length === 0) return 0;
+  const matchDistance = Math.floor(Math.max(s1.length, s2.length) / 2) - 1;
+  const s1Matches = new Array(s1.length).fill(false);
+  const s2Matches = new Array(s2.length).fill(false);
+  let matches = 0;
+  let transpositions = 0;
+  for (let i = 0; i < s1.length; i++) {
+    const start = Math.max(0, i - matchDistance);
+    const end = Math.min(i + matchDistance + 1, s2.length);
+    for (let j = start; j < end; j++) {
+      if (s2Matches[j] || s1[i] !== s2[j]) continue;
+      s1Matches[i] = true;
+      s2Matches[j] = true;
+      matches++;
+      break;
+    }
+  }
+  if (matches === 0) return 0;
+  let k = 0;
+  for (let i = 0; i < s1.length; i++) {
+    if (!s1Matches[i]) continue;
+    while (!s2Matches[k]) k++;
+    if (s1[i] !== s2[k]) transpositions++;
+    k++;
+  }
+  return (matches / s1.length + matches / s2.length + (matches - transpositions / 2) / matches) / 3;
+}
+function jaroWinklerSimilarity(s1, s2, prefixScale = 0.1) {
+  const jaroSim = jaroSimilarity(s1, s2);
+  let prefixLength = 0;
+  const maxPrefix = Math.min(4, Math.min(s1.length, s2.length));
+  for (let i = 0; i < maxPrefix; i++) {
+    if (s1[i] === s2[i]) {
+      prefixLength++;
+    } else {
+      break;
+    }
+  }
+  return jaroSim + prefixLength * prefixScale * (1 - jaroSim);
+}
+function generateNgrams(s, n) {
+  const ngrams = /* @__PURE__ */ new Set();
+  if (s.length < n) {
+    ngrams.add(s);
+    return ngrams;
+  }
+  for (let i = 0; i <= s.length - n; i++) {
+    ngrams.add(s.substring(i, i + n));
+  }
+  return ngrams;
+}
+function ngramSimilarity(s1, s2, n = 2) {
+  if (s1.length === 0 && s2.length === 0) return 1;
+  if (s1.length === 0 || s2.length === 0) return 0;
+  const ngrams1 = generateNgrams(s1, n);
+  const ngrams2 = generateNgrams(s2, n);
+  let intersection = 0;
+  for (const ngram of ngrams1) {
+    if (ngrams2.has(ngram)) {
+      intersection++;
+    }
+  }
+  const union = ngrams1.size + ngrams2.size - intersection;
+  return union === 0 ? 0 : intersection / union;
+}
+function normalizeString(s, config = {}) {
+  let normalized = s;
+  if (!config.caseSensitive) {
+    normalized = normalized.toLowerCase();
+  }
+  if (config.ignoreWhitespace !== false) {
+    normalized = normalized.replace(/\s+/g, " ").trim();
+  }
+  return normalized;
+}
+function fuzzyMatch(source, target, config = {}) {
+  const finalConfig = { ...DEFAULT_FUZZY_CONFIG, ...config };
+  const normalizedSource = normalizeString(source, finalConfig);
+  const normalizedTarget = normalizeString(target, finalConfig);
+  const levenshteinScore = levenshteinSimilarity(normalizedSource, normalizedTarget);
+  const jaroWinklerScore = jaroWinklerSimilarity(normalizedSource, normalizedTarget);
+  const ngramScore = ngramSimilarity(normalizedSource, normalizedTarget, finalConfig.ngramSize);
+  const similarity = levenshteinScore * finalConfig.levenshteinWeight + jaroWinklerScore * finalConfig.jaroWinklerWeight + ngramScore * finalConfig.ngramWeight;
+  return {
+    similarity,
+    isMatch: similarity >= finalConfig.threshold,
+    scores: {
+      levenshtein: levenshteinScore,
+      jaroWinkler: jaroWinklerScore,
+      ngram: ngramScore
+    },
+    normalizedSource,
+    normalizedTarget
+  };
+}
+function fuzzyContains(source, target, config = {}) {
+  const finalConfig = { ...DEFAULT_FUZZY_CONFIG, ...config };
+  const normalizedSource = normalizeString(source, finalConfig);
+  const normalizedTarget = normalizeString(target, finalConfig);
+  if (normalizedSource.includes(normalizedTarget)) {
+    return true;
+  }
+  const sourceWords = normalizedSource.split(/\s+/);
+  const targetWords = normalizedTarget.split(/\s+/);
+  for (const targetWord of targetWords) {
+    const hasMatch = sourceWords.some((sourceWord) => {
+      const result = fuzzyMatch(sourceWord, targetWord, { ...finalConfig, threshold: 0.8 });
+      return result.isMatch;
+    });
+    if (!hasMatch) {
+      return false;
+    }
+  }
+  return true;
+}
+function wordSimilarity(s1, s2, config = {}) {
+  const finalConfig = { ...DEFAULT_FUZZY_CONFIG, ...config };
+  const words1 = normalizeString(s1, finalConfig).split(/\s+/);
+  const words2 = normalizeString(s2, finalConfig).split(/\s+/);
+  if (words1.length === 0 && words2.length === 0) return 1;
+  if (words1.length === 0 || words2.length === 0) return 0;
+  let totalSimilarity = 0;
+  let matchCount = 0;
+  for (const word1 of words1) {
+    let bestSim = 0;
+    for (const word2 of words2) {
+      const result = fuzzyMatch(word1, word2, finalConfig);
+      if (result.similarity > bestSim) {
+        bestSim = result.similarity;
+      }
+    }
+    totalSimilarity += bestSim;
+    if (bestSim >= finalConfig.threshold) {
+      matchCount++;
+    }
+  }
+  const avgSimilarity = totalSimilarity / words1.length;
+  const matchRatio = matchCount / Math.max(words1.length, words2.length);
+  return avgSimilarity * 0.5 + matchRatio * 0.5;
+}
+function tokenize(s) {
+  return s.replace(/([a-z])([A-Z])/g, "$1 $2").replace(/[_-]/g, " ").replace(/\s+/g, " ").trim().toLowerCase().split(" ").filter((token) => token.length > 0);
+}
+function tokenSimilarity(s1, s2) {
+  const tokens1 = tokenize(s1);
+  const tokens2 = tokenize(s2);
+  if (tokens1.length === 0 && tokens2.length === 0) return 1;
+  if (tokens1.length === 0 || tokens2.length === 0) return 0;
+  const set1 = new Set(tokens1);
+  const set2 = new Set(tokens2);
+  let intersection = 0;
+  for (const token of set1) {
+    if (set2.has(token)) {
+      intersection++;
+    }
+  }
+  const union = set1.size + set2.size - intersection;
+  return union === 0 ? 0 : intersection / union;
+}
+
+// src/ai/alias-generator.ts
+var DEFAULT_ALIAS_CONFIG = {
+  includeText: true,
+  includeAriaLabel: true,
+  includePlaceholder: true,
+  includeTitle: true,
+  includeSynonyms: true,
+  maxAliases: 20,
+  minLength: 2,
+  maxLength: 50
+};
+var SYNONYMS = {
+  // Submit-related
+  submit: ["send", "go", "confirm", "ok", "apply", "save", "done", "finish"],
+  send: ["submit", "deliver", "post"],
+  save: ["submit", "store", "keep", "apply"],
+  cancel: ["close", "dismiss", "abort", "back", "exit", "quit", "nevermind"],
+  close: ["cancel", "dismiss", "exit", "x"],
+  delete: ["remove", "trash", "erase", "clear", "destroy"],
+  remove: ["delete", "clear", "discard"],
+  edit: ["modify", "change", "update", "alter"],
+  update: ["edit", "modify", "save", "refresh"],
+  add: ["create", "new", "plus", "insert"],
+  create: ["add", "new", "make"],
+  search: ["find", "lookup", "query", "filter"],
+  find: ["search", "locate", "lookup"],
+  login: ["signin", "sign in", "log in", "authenticate", "enter"],
+  logout: ["signout", "sign out", "log out", "exit"],
+  register: ["signup", "sign up", "join", "create account"],
+  next: ["continue", "forward", "proceed", "advance"],
+  previous: ["back", "backward", "return", "prior"],
+  back: ["previous", "return", "backward"],
+  start: ["begin", "launch", "initiate", "run", "execute"],
+  stop: ["end", "halt", "pause", "terminate"],
+  enable: ["activate", "turn on", "switch on"],
+  disable: ["deactivate", "turn off", "switch off"],
+  show: ["display", "reveal", "view", "open"],
+  hide: ["conceal", "collapse", "close"],
+  expand: ["open", "show", "unfold", "reveal"],
+  collapse: ["close", "hide", "fold", "minimize"],
+  yes: ["ok", "confirm", "agree", "accept"],
+  no: ["cancel", "decline", "reject", "deny"],
+  help: ["support", "assistance", "info", "information", "faq"],
+  settings: ["preferences", "options", "config", "configuration"],
+  profile: ["account", "user", "me"],
+  download: ["export", "save", "get"],
+  upload: ["import", "load", "attach"],
+  refresh: ["reload", "update", "sync"],
+  copy: ["duplicate", "clone"],
+  paste: ["insert"],
+  select: ["choose", "pick"],
+  toggle: ["switch", "flip"],
+  // Form fields
+  email: ["e-mail", "mail"],
+  password: ["pass", "pwd", "secret"],
+  username: ["user", "login", "account", "name"],
+  firstname: ["first name", "given name", "forename"],
+  lastname: ["last name", "surname", "family name"],
+  fullname: ["full name", "name", "complete name"],
+  phone: ["telephone", "tel", "mobile", "cell"],
+  address: ["location", "street"],
+  city: ["town"],
+  country: ["nation"],
+  zip: ["zipcode", "postal", "postal code", "postcode"],
+  // Navigation
+  home: ["main", "start", "dashboard"],
+  menu: ["navigation", "nav"],
+  sidebar: ["side bar", "side panel", "side menu"]
+};
+var ELEMENT_ACTION_WORDS = {
+  button: ["button", "btn", "click"],
+  input: ["input", "field", "textbox", "box"],
+  textarea: ["textarea", "text area", "text field", "multiline"],
+  select: ["select", "dropdown", "combo", "picker", "chooser"],
+  checkbox: ["checkbox", "check", "tick"],
+  radio: ["radio", "option", "choice"],
+  link: ["link", "anchor", "href"],
+  form: ["form"],
+  menu: ["menu"],
+  menuitem: ["menu item", "option"],
+  tab: ["tab"],
+  dialog: ["dialog", "modal", "popup"],
+  switch: ["switch", "toggle"],
+  slider: ["slider", "range"]
+};
+function normalizeAlias(text) {
+  return text.toLowerCase().replace(/[^\w\s]/g, " ").replace(/\s+/g, " ").trim();
+}
+function extractWords(text) {
+  const tokens = tokenize(text);
+  return tokens.filter((t) => t.length >= 2);
+}
+function generateTextAliases(text, config) {
+  if (!text || !config.includeText) return [];
+  const aliases = [];
+  const normalized = normalizeAlias(text);
+  if (normalized.length >= config.minLength && normalized.length <= config.maxLength) {
+    aliases.push(normalized);
+  }
+  const words = extractWords(text);
+  for (const word of words) {
+    if (word.length >= config.minLength) {
+      aliases.push(word);
+    }
+  }
+  if (words.length >= 2 && words.length <= 4) {
+    const twoWords = words.slice(0, 2).join(" ");
+    if (twoWords.length <= config.maxLength) {
+      aliases.push(twoWords);
+    }
+    if (words.length > 2) {
+      const lastTwo = words.slice(-2).join(" ");
+      if (lastTwo.length <= config.maxLength) {
+        aliases.push(lastTwo);
+      }
+    }
+  }
+  return aliases;
+}
+function generateSynonyms(aliases, config) {
+  if (!config.includeSynonyms) return [];
+  const synonyms = [];
+  for (const alias of aliases) {
+    const words = alias.toLowerCase().split(/\s+/);
+    for (const word of words) {
+      if (SYNONYMS[word]) {
+        for (const synonym of SYNONYMS[word]) {
+          const newAlias = alias.toLowerCase().replace(word, synonym);
+          if (newAlias !== alias.toLowerCase()) {
+            synonyms.push(newAlias);
+          }
+          if (synonym.length >= config.minLength) {
+            synonyms.push(synonym);
+          }
+        }
+      }
+    }
+  }
+  return synonyms;
+}
+function generateTypeAliases(elementType) {
+  const type = elementType.toLowerCase();
+  return ELEMENT_ACTION_WORDS[type] || [type];
+}
+function generateAliases(input, config = {}) {
+  const finalConfig = { ...DEFAULT_ALIAS_CONFIG, ...config };
+  const aliasSet = /* @__PURE__ */ new Set();
+  const addAlias = (alias) => {
+    const normalized = normalizeAlias(alias);
+    if (normalized.length >= finalConfig.minLength && normalized.length <= finalConfig.maxLength) {
+      aliasSet.add(normalized);
+    }
+  };
+  const addAliases = (aliases2) => {
+    for (const alias of aliases2) {
+      addAlias(alias);
+    }
+  };
+  if (finalConfig.includeText && input.textContent) {
+    addAliases(generateTextAliases(input.textContent, finalConfig));
+  }
+  if (finalConfig.includeAriaLabel && input.ariaLabel) {
+    addAliases(generateTextAliases(input.ariaLabel, finalConfig));
+  }
+  if (finalConfig.includeAriaLabel && input.ariaLabelledBy) {
+    addAliases(generateTextAliases(input.ariaLabelledBy, finalConfig));
+  }
+  if (finalConfig.includePlaceholder && input.placeholder) {
+    addAliases(generateTextAliases(input.placeholder, finalConfig));
+  }
+  if (finalConfig.includeTitle && input.title) {
+    addAliases(generateTextAliases(input.title, finalConfig));
+  }
+  if (input.labelText) {
+    addAliases(generateTextAliases(input.labelText, finalConfig));
+  }
+  if (input.id) {
+    addAliases(extractWords(input.id));
+  }
+  if (input.name) {
+    addAliases(extractWords(input.name));
+  }
+  if (input.value && (input.elementType === "button" || input.inputType === "submit" || input.inputType === "button")) {
+    addAliases(generateTextAliases(input.value, finalConfig));
+  }
+  if (input.elementType) {
+    addAliases(generateTypeAliases(input.elementType));
+  }
+  if (input.inputType) {
+    addAlias(input.inputType);
+    if (input.inputType === "email") {
+      addAliases(["email", "e-mail", "email address"]);
+    } else if (input.inputType === "password") {
+      addAliases(["password", "pass", "pwd"]);
+    } else if (input.inputType === "tel") {
+      addAliases(["phone", "telephone", "mobile"]);
+    } else if (input.inputType === "url") {
+      addAliases(["url", "website", "link", "address"]);
+    } else if (input.inputType === "search") {
+      addAliases(["search", "find", "query"]);
+    }
+  }
+  if (finalConfig.includeSynonyms) {
+    const currentAliases = Array.from(aliasSet);
+    addAliases(generateSynonyms(currentAliases, finalConfig));
+  }
+  let aliases = Array.from(aliasSet);
+  aliases.sort((a, b) => a.length - b.length);
+  if (aliases.length > finalConfig.maxAliases) {
+    aliases = aliases.slice(0, finalConfig.maxAliases);
+  }
+  return aliases;
+}
+function generateDescription(input) {
+  const parts = [];
+  let name = input.ariaLabel || input.labelText || input.textContent || input.placeholder || input.title || input.id || input.name;
+  if (name) {
+    name = name.trim();
+    if (name.length > 30) {
+      name = name.substring(0, 27) + "...";
+    }
+    parts.push(`"${name}"`);
+  }
+  const typeWords = ELEMENT_ACTION_WORDS[input.elementType || ""] || [input.elementType || "element"];
+  parts.push(typeWords[0]);
+  if (input.inputType && input.inputType !== "text") {
+    parts.push(`(${input.inputType})`);
+  }
+  return parts.join(" ");
+}
+function generatePurpose(input) {
+  const text = (input.textContent || input.ariaLabel || input.title || "").toLowerCase();
+  const type = input.elementType?.toLowerCase() || "";
+  const inputType = input.inputType?.toLowerCase() || "";
+  if (type === "button" || inputType === "submit") {
+    if (text.match(/submit|send|save|confirm|ok|done|finish|apply/)) {
+      return "Submits the form";
+    }
+    if (text.match(/cancel|close|dismiss|back|exit/)) {
+      return "Cancels or closes the current action";
+    }
+    if (text.match(/delete|remove|trash|clear/)) {
+      return "Deletes or removes an item";
+    }
+    if (text.match(/edit|modify|change|update/)) {
+      return "Edits or modifies an item";
+    }
+    if (text.match(/add|create|new|\+/)) {
+      return "Creates or adds a new item";
+    }
+    if (text.match(/search|find|lookup/)) {
+      return "Performs a search";
+    }
+    if (text.match(/login|sign.?in/)) {
+      return "Signs the user in";
+    }
+    if (text.match(/logout|sign.?out/)) {
+      return "Signs the user out";
+    }
+    if (text.match(/register|sign.?up|join/)) {
+      return "Creates a new account";
+    }
+    if (text.match(/next|continue|proceed/)) {
+      return "Proceeds to the next step";
+    }
+    if (text.match(/previous|back|return/)) {
+      return "Returns to the previous step";
+    }
+  }
+  if (type === "input" || type === "textarea") {
+    if (inputType === "email") return "Accepts email address input";
+    if (inputType === "password") return "Accepts password input";
+    if (inputType === "search") return "Accepts search query input";
+    if (inputType === "tel") return "Accepts phone number input";
+    if (inputType === "url") return "Accepts URL input";
+    if (inputType === "number") return "Accepts numeric input";
+    if (inputType === "date") return "Accepts date input";
+    if (inputType === "file") return "Accepts file upload";
+  }
+  if (type === "checkbox") {
+    return "Toggles an option on or off";
+  }
+  if (type === "radio") {
+    return "Selects one option from a group";
+  }
+  if (type === "select") {
+    return "Selects an option from a dropdown";
+  }
+  if (type === "link") {
+    return "Navigates to another page";
+  }
+  return void 0;
+}
+function generateSuggestedActions(input) {
+  const type = input.elementType?.toLowerCase() || "";
+  const inputType = input.inputType?.toLowerCase() || "";
+  const text = (input.textContent || input.ariaLabel || "").toLowerCase();
+  const actions = [];
+  switch (type) {
+    case "button":
+      actions.push(`click "${text || "this button"}"`);
+      break;
+    case "input":
+      if (inputType === "checkbox") {
+        actions.push("check to enable", "uncheck to disable");
+      } else if (inputType === "radio") {
+        actions.push("select this option");
+      } else {
+        actions.push(`type into "${text || "this field"}"`);
+        actions.push("clear the field");
+      }
+      break;
+    case "textarea":
+      actions.push(`type into "${text || "this text area"}"`);
+      actions.push("clear the content");
+      break;
+    case "select":
+      actions.push(`select an option from "${text || "this dropdown"}"`);
+      break;
+    case "checkbox":
+      actions.push("check to enable", "uncheck to disable");
+      break;
+    case "radio":
+      actions.push("select this option");
+      break;
+    case "link":
+      actions.push(`click to navigate to "${text || "the linked page"}"`);
+      break;
+    case "switch":
+      actions.push("toggle on", "toggle off");
+      break;
+    default:
+      actions.push("click");
+  }
+  return actions;
+}
+function areSynonyms(word1, word2) {
+  const w1 = word1.toLowerCase().trim();
+  const w2 = word2.toLowerCase().trim();
+  if (w1 === w2) return true;
+  const synonyms1 = SYNONYMS[w1] || [];
+  const synonyms2 = SYNONYMS[w2] || [];
+  return synonyms1.includes(w2) || synonyms2.includes(w1);
+}
+
+// src/ai/search-engine.ts
+var DEFAULT_SEARCH_CONFIG = {
+  fuzzyThreshold: 0.7,
+  textWeight: 0.35,
+  accessibilityWeight: 0.25,
+  roleWeight: 0.15,
+  spatialWeight: 0.1,
+  aliasWeight: 0.15,
+  maxResults: 20,
+  includeHidden: false
+};
+var SearchEngine = class {
+  // Cache valid for 100ms
+  constructor(config = {}) {
+    this.cachedElements = [];
+    this.cacheTimestamp = 0;
+    this.cacheValidityMs = 100;
+    this.config = { ...DEFAULT_SEARCH_CONFIG, ...config };
+  }
+  /**
+   * Update cached elements from various sources
+   */
+  updateElements(elements, getState) {
+    this.cachedElements = elements.map((el) => this.toSearchable(el, getState));
+    this.cacheTimestamp = Date.now();
+  }
+  /**
+   * Convert an element to searchable format
+   */
+  toSearchable(element, getState) {
+    let state;
+    let textContent;
+    let tagName;
+    let role;
+    let ariaLabel;
+    let placeholder;
+    let title;
+    let labelText;
+    let value;
+    if ("getState" in element && typeof element.getState === "function") {
+      state = getState ? getState(element) : element.getState();
+      textContent = state.textContent || void 0;
+      tagName = element.element.tagName.toLowerCase();
+      role = element.element.getAttribute("role") || void 0;
+      ariaLabel = element.element.getAttribute("aria-label") || void 0;
+      placeholder = element.element.getAttribute("placeholder") || void 0;
+      title = element.element.getAttribute("title") || void 0;
+      if (element.element.id) {
+        const labelEl = document.querySelector(`label[for="${element.element.id}"]`);
+        labelText = labelEl?.textContent?.trim() || void 0;
+      }
+      if (element.element instanceof HTMLInputElement || element.element instanceof HTMLTextAreaElement || element.element instanceof HTMLSelectElement) {
+        value = element.element.value || void 0;
+      }
+    } else {
+      const discovered = element;
+      state = discovered.state;
+      textContent = state.textContent || void 0;
+      tagName = discovered.tagName;
+      role = discovered.role || void 0;
+      ariaLabel = discovered.accessibleName || void 0;
+    }
+    const aliases = generateAliases({
+      textContent,
+      ariaLabel,
+      placeholder,
+      title,
+      elementType: element.type,
+      id: element.id,
+      labelText,
+      value
+    });
+    const description = generateDescription({
+      textContent,
+      ariaLabel,
+      placeholder,
+      title,
+      elementType: element.type,
+      id: element.id,
+      labelText
+    });
+    return {
+      id: element.id,
+      element,
+      state,
+      textContent,
+      ariaLabel,
+      placeholder,
+      title,
+      role,
+      tagName,
+      type: element.type,
+      aliases,
+      description,
+      rect: state.rect,
+      labelText,
+      value
+    };
+  }
+  /**
+   * Search for elements matching the criteria
+   */
+  search(criteria, elements) {
+    const startTime = performance.now();
+    if (elements) {
+      this.updateElements(elements);
+    }
+    let searchableElements = this.cachedElements;
+    if (!this.config.includeHidden && !criteria.fuzzy) {
+      searchableElements = searchableElements.filter((el) => el.state.visible);
+    }
+    const results = [];
+    for (const searchable of searchableElements) {
+      const result = this.scoreElement(searchable, criteria);
+      if (result.confidence >= (criteria.fuzzyThreshold ?? this.config.fuzzyThreshold)) {
+        results.push(result);
+      }
+    }
+    results.sort((a, b) => b.confidence - a.confidence);
+    const limitedResults = results.slice(0, this.config.maxResults);
+    return {
+      results: limitedResults,
+      bestMatch: limitedResults.length > 0 ? limitedResults[0] : null,
+      scannedCount: searchableElements.length,
+      durationMs: performance.now() - startTime,
+      criteria,
+      timestamp: Date.now()
+    };
+  }
+  /**
+   * Find the best matching element
+   */
+  findBest(criteria, elements) {
+    const response = this.search(criteria, elements);
+    return response.bestMatch;
+  }
+  /**
+   * Find elements by text content
+   */
+  findByText(text, fuzzy = true, elements) {
+    return this.search({ text, fuzzy }, elements).results;
+  }
+  /**
+   * Find elements by role
+   */
+  findByRole(role, name, elements) {
+    const criteria = { role };
+    if (name) {
+      criteria.accessibleName = name;
+    }
+    return this.search(criteria, elements).results;
+  }
+  /**
+   * Find elements by accessible name
+   */
+  findByAccessibleName(name, elements) {
+    return this.search({ accessibleName: name, fuzzy: true }, elements).results;
+  }
+  /**
+   * Find elements near another element
+   */
+  findNear(referenceId, criteria, elements) {
+    return this.search({ ...criteria, near: referenceId }, elements).results;
+  }
+  /**
+   * Find elements within a container
+   */
+  findWithin(containerId, criteria, elements) {
+    return this.search({ ...criteria, within: containerId }, elements).results;
+  }
+  /**
+   * Score an element against search criteria
+   */
+  scoreElement(searchable, criteria) {
+    const scores = {};
+    const matchReasons = [];
+    let totalWeight = 0;
+    let weightedScore = 0;
+    const fuzzyConfig = {
+      ...DEFAULT_FUZZY_CONFIG,
+      threshold: criteria.fuzzyThreshold ?? this.config.fuzzyThreshold
+    };
+    if (criteria.text) {
+      const textScore = this.scoreTextMatch(searchable, criteria.text, criteria.fuzzy !== false, fuzzyConfig.threshold);
+      scores.text = textScore.score;
+      if (textScore.score > 0) {
+        matchReasons.push(...textScore.reasons);
+      }
+      weightedScore += textScore.score * this.config.textWeight;
+      totalWeight += this.config.textWeight;
+    }
+    if (criteria.textContains) {
+      const containsScore = this.scoreContainsMatch(searchable, criteria.textContains, criteria.fuzzy !== false);
+      scores.text = Math.max(scores.text || 0, containsScore.score);
+      if (containsScore.score > 0 && containsScore.reasons.length > 0) {
+        matchReasons.push(...containsScore.reasons);
+      }
+      weightedScore += containsScore.score * this.config.textWeight;
+      totalWeight += this.config.textWeight;
+    }
+    if (criteria.accessibleName) {
+      const accessibilityScore = this.scoreAccessibilityMatch(
+        searchable,
+        criteria.accessibleName,
+        criteria.fuzzy !== false,
+        fuzzyConfig.threshold
+      );
+      scores.accessibility = accessibilityScore.score;
+      if (accessibilityScore.score > 0) {
+        matchReasons.push(...accessibilityScore.reasons);
+      }
+      weightedScore += accessibilityScore.score * this.config.accessibilityWeight;
+      totalWeight += this.config.accessibilityWeight;
+    }
+    if (criteria.role) {
+      const roleScore = this.scoreRoleMatch(searchable, criteria.role);
+      scores.role = roleScore.score;
+      if (roleScore.score > 0) {
+        matchReasons.push(...roleScore.reasons);
+      }
+      weightedScore += roleScore.score * this.config.roleWeight;
+      totalWeight += this.config.roleWeight;
+    }
+    if (criteria.type) {
+      const typeMatch = searchable.type.toLowerCase() === criteria.type.toLowerCase();
+      if (typeMatch) {
+        matchReasons.push(`type: ${criteria.type}`);
+        weightedScore += 1 * this.config.roleWeight;
+        totalWeight += this.config.roleWeight;
+      }
+    }
+    if (criteria.near) {
+      const spatialScore = this.scoreSpatialMatch(searchable, criteria.near);
+      scores.spatial = spatialScore.score;
+      if (spatialScore.score > 0) {
+        matchReasons.push(...spatialScore.reasons);
+      }
+      weightedScore += spatialScore.score * this.config.spatialWeight;
+      totalWeight += this.config.spatialWeight;
+    }
+    if (criteria.placeholder && searchable.placeholder) {
+      const placeholderResult = fuzzyMatch(searchable.placeholder, criteria.placeholder, fuzzyConfig);
+      if (placeholderResult.isMatch) {
+        matchReasons.push(`placeholder matches`);
+        weightedScore += placeholderResult.similarity * this.config.textWeight;
+        totalWeight += this.config.textWeight;
+      }
+    }
+    if (criteria.title && searchable.title) {
+      const titleResult = fuzzyMatch(searchable.title, criteria.title, fuzzyConfig);
+      if (titleResult.isMatch) {
+        matchReasons.push(`title matches`);
+        weightedScore += titleResult.similarity * this.config.textWeight;
+        totalWeight += this.config.textWeight;
+      }
+    }
+    if (criteria.idPattern) {
+      const idMatch = this.matchPattern(searchable.id, criteria.idPattern);
+      if (idMatch) {
+        matchReasons.push(`id matches pattern`);
+        weightedScore += 1 * this.config.textWeight;
+        totalWeight += this.config.textWeight;
+      }
+    }
+    const aliasScore = this.scoreAliasMatch(searchable, criteria, fuzzyConfig.threshold);
+    if (aliasScore.score > 0) {
+      scores.fuzzy = aliasScore.score;
+      matchReasons.push(...aliasScore.reasons);
+      weightedScore += aliasScore.score * this.config.aliasWeight;
+      totalWeight += this.config.aliasWeight;
+    }
+    const confidence = totalWeight > 0 ? weightedScore / totalWeight : 0;
+    const aiElement = this.toAIDiscoveredElement(searchable);
+    return {
+      element: aiElement,
+      confidence,
+      matchReasons,
+      scores
+    };
+  }
+  /**
+   * Score text match
+   */
+  scoreTextMatch(searchable, text, fuzzy, threshold) {
+    const reasons = [];
+    let maxScore = 0;
+    const textsToMatch = [
+      searchable.textContent,
+      searchable.labelText,
+      searchable.value
+    ].filter(Boolean);
+    for (const targetText of textsToMatch) {
+      if (targetText.toLowerCase() === text.toLowerCase()) {
+        maxScore = Math.max(maxScore, 1);
+        reasons.push("exact text match");
+        continue;
+      }
+      if (fuzzy) {
+        const result = fuzzyMatch(targetText, text, { threshold });
+        if (result.isMatch && result.similarity > maxScore) {
+          maxScore = result.similarity;
+          reasons.push(`text similarity: ${(result.similarity * 100).toFixed(0)}%`);
+        }
+        const wordSim = wordSimilarity(targetText, text, { threshold });
+        if (wordSim > maxScore && wordSim >= threshold) {
+          maxScore = wordSim;
+          reasons.push(`word match: ${(wordSim * 100).toFixed(0)}%`);
+        }
+      }
+    }
+    return { score: maxScore, reasons };
+  }
+  /**
+   * Score contains match
+   */
+  scoreContainsMatch(searchable, text, fuzzy) {
+    const reasons = [];
+    let maxScore = 0;
+    const textsToMatch = [
+      searchable.textContent,
+      searchable.labelText,
+      searchable.ariaLabel
+    ].filter(Boolean);
+    for (const targetText of textsToMatch) {
+      if (targetText.toLowerCase().includes(text.toLowerCase())) {
+        maxScore = Math.max(maxScore, 0.9);
+        reasons.push("text contains match");
+        continue;
+      }
+      if (fuzzy && fuzzyContains(targetText, text)) {
+        maxScore = Math.max(maxScore, 0.7);
+        reasons.push("fuzzy contains match");
+      }
+    }
+    return { score: maxScore, reasons };
+  }
+  /**
+   * Score accessibility match
+   */
+  scoreAccessibilityMatch(searchable, name, fuzzy, threshold) {
+    const reasons = [];
+    let maxScore = 0;
+    const accessibleNames = [
+      searchable.ariaLabel,
+      searchable.ariaLabelledBy,
+      searchable.labelText,
+      searchable.title
+    ].filter(Boolean);
+    for (const accessibleName of accessibleNames) {
+      if (accessibleName.toLowerCase() === name.toLowerCase()) {
+        maxScore = Math.max(maxScore, 1);
+        reasons.push("exact accessible name match");
+        continue;
+      }
+      if (fuzzy) {
+        const result = fuzzyMatch(accessibleName, name, { threshold });
+        if (result.isMatch && result.similarity > maxScore) {
+          maxScore = result.similarity;
+          reasons.push(`accessible name similarity: ${(result.similarity * 100).toFixed(0)}%`);
+        }
+      }
+    }
+    return { score: maxScore, reasons };
+  }
+  /**
+   * Score role match
+   */
+  scoreRoleMatch(searchable, role) {
+    const reasons = [];
+    const normalizedRole = role.toLowerCase();
+    if (searchable.role?.toLowerCase() === normalizedRole) {
+      return { score: 1, reasons: [`role: ${role}`] };
+    }
+    const tagRoleMap = {
+      button: ["button", "input[type=button]", "input[type=submit]"],
+      textbox: ["input", "textarea"],
+      checkbox: ["input[type=checkbox]"],
+      radio: ["input[type=radio]"],
+      link: ["a"],
+      listbox: ["select"],
+      combobox: ["select", "input[list]"],
+      navigation: ["nav"],
+      main: ["main"],
+      heading: ["h1", "h2", "h3", "h4", "h5", "h6"]
+    };
+    const inferredRoles = tagRoleMap[normalizedRole] || [];
+    if (inferredRoles.some((r) => searchable.tagName === r || searchable.type.toLowerCase() === normalizedRole)) {
+      return { score: 0.8, reasons: [`inferred role: ${role}`] };
+    }
+    return { score: 0, reasons };
+  }
+  /**
+   * Score spatial match (proximity to another element)
+   */
+  scoreSpatialMatch(searchable, nearId) {
+    const reference = this.cachedElements.find((el) => el.id === nearId);
+    if (!reference) {
+      return { score: 0, reasons: [] };
+    }
+    const distance = this.calculateDistance(searchable.rect, reference.rect);
+    const nearThreshold = 200;
+    if (distance > nearThreshold * 3) {
+      return { score: 0, reasons: [] };
+    }
+    const score = Math.max(0, 1 - distance / (nearThreshold * 3));
+    return {
+      score,
+      reasons: [`${distance.toFixed(0)}px from ${nearId}`]
+    };
+  }
+  /**
+   * Calculate distance between two element rectangles
+   */
+  calculateDistance(rect1, rect2) {
+    const center1 = {
+      x: rect1.x + rect1.width / 2,
+      y: rect1.y + rect1.height / 2
+    };
+    const center2 = {
+      x: rect2.x + rect2.width / 2,
+      y: rect2.y + rect2.height / 2
+    };
+    return Math.sqrt(Math.pow(center1.x - center2.x, 2) + Math.pow(center1.y - center2.y, 2));
+  }
+  /**
+   * Score alias match
+   */
+  scoreAliasMatch(searchable, criteria, threshold) {
+    const reasons = [];
+    let maxScore = 0;
+    const searchTerms = [];
+    if (criteria.text) searchTerms.push(criteria.text);
+    if (criteria.textContains) searchTerms.push(criteria.textContains);
+    if (criteria.accessibleName) searchTerms.push(criteria.accessibleName);
+    for (const searchTerm of searchTerms) {
+      const termLower = searchTerm.toLowerCase();
+      for (const alias of searchable.aliases) {
+        if (alias === termLower) {
+          maxScore = Math.max(maxScore, 1);
+          reasons.push(`alias match: "${alias}"`);
+          continue;
+        }
+        const searchWords = termLower.split(/\s+/);
+        const aliasWords = alias.split(/\s+/);
+        for (const searchWord of searchWords) {
+          for (const aliasWord of aliasWords) {
+            if (areSynonyms(searchWord, aliasWord)) {
+              maxScore = Math.max(maxScore, 0.85);
+              reasons.push(`synonym match: "${searchWord}" ~ "${aliasWord}"`);
+            }
+          }
+        }
+        const result = fuzzyMatch(alias, termLower, { threshold });
+        if (result.isMatch && result.similarity > maxScore) {
+          maxScore = result.similarity;
+          reasons.push(`fuzzy alias: "${alias}" (${(result.similarity * 100).toFixed(0)}%)`);
+        }
+        const tokenSim = tokenSimilarity(alias, termLower);
+        if (tokenSim > maxScore && tokenSim >= threshold) {
+          maxScore = tokenSim;
+          reasons.push(`token match: "${alias}"`);
+        }
+      }
+    }
+    return { score: maxScore, reasons };
+  }
+  /**
+   * Match a string against a pattern (supports * wildcard)
+   */
+  matchPattern(str, pattern) {
+    const regexPattern = pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&").replace(/\\\*/g, ".*");
+    return new RegExp(`^${regexPattern}$`, "i").test(str);
+  }
+  /**
+   * Convert searchable element to AI discovered element
+   */
+  toAIDiscoveredElement(searchable) {
+    const discoveredBase = "getState" in searchable.element ? {
+      id: searchable.id,
+      type: searchable.type,
+      label: searchable.element.label,
+      tagName: searchable.tagName,
+      role: searchable.role,
+      accessibleName: searchable.ariaLabel,
+      actions: searchable.element.actions,
+      state: searchable.state,
+      registered: true
+    } : searchable.element;
+    return {
+      ...discoveredBase,
+      description: searchable.description,
+      aliases: searchable.aliases,
+      purpose: generatePurpose({
+        textContent: searchable.textContent,
+        ariaLabel: searchable.ariaLabel,
+        elementType: searchable.type,
+        tagName: searchable.tagName
+      }),
+      parentContext: void 0,
+      // Would need DOM traversal
+      suggestedActions: generateSuggestedActions({
+        textContent: searchable.textContent,
+        ariaLabel: searchable.ariaLabel,
+        elementType: searchable.type,
+        tagName: searchable.tagName
+      }),
+      semanticType: this.inferSemanticType(searchable),
+      labelText: searchable.labelText,
+      placeholder: searchable.placeholder,
+      title: searchable.title
+    };
+  }
+  /**
+   * Infer a semantic type for the element
+   */
+  inferSemanticType(searchable) {
+    const text = (searchable.textContent || searchable.ariaLabel || "").toLowerCase();
+    const type = searchable.type.toLowerCase();
+    if (type === "input" || type === "textarea") {
+      if (searchable.placeholder?.toLowerCase().includes("email") || text.includes("email")) {
+        return "email-input";
+      }
+      if (searchable.placeholder?.toLowerCase().includes("password") || text.includes("password")) {
+        return "password-input";
+      }
+      if (searchable.placeholder?.toLowerCase().includes("search") || text.includes("search")) {
+        return "search-input";
+      }
+      return "text-input";
+    }
+    if (type === "button") {
+      if (text.match(/submit|save|confirm|ok|done|apply/)) return "submit-button";
+      if (text.match(/cancel|close|dismiss/)) return "cancel-button";
+      if (text.match(/delete|remove|trash/)) return "delete-button";
+      if (text.match(/add|create|new|\+/)) return "add-button";
+      if (text.match(/edit|modify/)) return "edit-button";
+      if (text.match(/next|continue/)) return "next-button";
+      if (text.match(/back|previous/)) return "back-button";
+      return "action-button";
+    }
+    if (type === "link") {
+      if (text.match(/home|dashboard/)) return "home-link";
+      if (text.match(/login|sign.?in/)) return "login-link";
+      if (text.match(/logout|sign.?out/)) return "logout-link";
+      return "navigation-link";
+    }
+    return type;
+  }
+};
+
+// src/ai/summary-generator.ts
+var DEFAULT_SUMMARY_CONFIG = {
+  maxLength: 2e3,
+  includeForms: true,
+  includeElementCounts: true,
+  includeModals: true,
+  includeFocused: true,
+  verbosity: "normal"
+};
+function generatePageSummary(elements, pageContext, config = {}) {
+  const finalConfig = { ...DEFAULT_SUMMARY_CONFIG, ...config };
+  const lines = [];
+  if (pageContext) {
+    if (pageContext.title) {
+      lines.push(`Page: "${pageContext.title}"`);
+    }
+    if (pageContext.pageType && pageContext.pageType !== "unknown") {
+      lines.push(`Type: ${formatPageType(pageContext.pageType)}`);
+    }
+  }
+  if (finalConfig.includeElementCounts) {
+    const counts = countElementTypes(elements);
+    const countParts = [];
+    if (counts.button > 0) countParts.push(`${counts.button} button${counts.button > 1 ? "s" : ""}`);
+    if (counts.input > 0) countParts.push(`${counts.input} input${counts.input > 1 ? "s" : ""}`);
+    if (counts.link > 0) countParts.push(`${counts.link} link${counts.link > 1 ? "s" : ""}`);
+    if (counts.select > 0) countParts.push(`${counts.select} dropdown${counts.select > 1 ? "s" : ""}`);
+    if (counts.checkbox > 0) countParts.push(`${counts.checkbox} checkbox${counts.checkbox > 1 ? "es" : ""}`);
+    if (countParts.length > 0) {
+      lines.push(`Contains: ${countParts.join(", ")}`);
+    }
+  }
+  if (finalConfig.includeForms) {
+    const forms = detectForms(elements);
+    if (forms.length > 0) {
+      lines.push("");
+      lines.push("Forms:");
+      for (const form of forms) {
+        lines.push(generateFormSummary(form, finalConfig.verbosity));
+      }
+    }
+  }
+  if (finalConfig.includeModals && pageContext?.activeModals && pageContext.activeModals.length > 0) {
+    lines.push("");
+    lines.push(`Active modals: ${pageContext.activeModals.join(", ")}`);
+  }
+  if (finalConfig.includeFocused && pageContext?.focusedElement) {
+    lines.push(`Focus: ${pageContext.focusedElement}`);
+  }
+  const keyElements = getKeyElements(elements);
+  if (keyElements.length > 0) {
+    lines.push("");
+    lines.push("Key elements:");
+    for (const el of keyElements) {
+      lines.push(`  - ${el.description}${el.state.enabled ? "" : " (disabled)"}`);
+    }
+  }
+  let summary = lines.join("\n");
+  if (summary.length > finalConfig.maxLength) {
+    summary = summary.substring(0, finalConfig.maxLength - 3) + "...";
+  }
+  return summary;
+}
+function generateFormSummary(form, verbosity) {
+  const lines = [];
+  const formName = form.name || form.purpose || form.id;
+  lines.push(`  ${formName}:`);
+  if (verbosity === "brief") {
+    const fieldCount = form.fields.length;
+    const filledCount = form.fields.filter((f) => f.value).length;
+    lines.push(`    ${filledCount}/${fieldCount} fields filled, ${form.isValid ? "valid" : "has errors"}`);
+  } else {
+    for (const field of form.fields) {
+      let fieldLine = `    - ${field.label || field.id}`;
+      if (field.value) {
+        fieldLine += ` = "${truncate(field.value, 15)}"`;
+      } else if (field.placeholder) {
+        fieldLine += ` (${field.placeholder})`;
+      } else {
+        fieldLine += " (empty)";
+      }
+      if (!field.valid && field.error) {
+        fieldLine += ` [ERROR: ${field.error}]`;
+      } else if (field.required && !field.value) {
+        fieldLine += " [required]";
+      }
+      lines.push(fieldLine);
+    }
+    if (form.submitButton) {
+      lines.push(`    Submit: ${form.submitButton}`);
+    }
+  }
+  return lines.join("\n");
+}
+function generateDiffSummary(appeared, disappeared, modified) {
+  const lines = [];
+  if (appeared.length > 0) {
+    lines.push(`Appeared: ${appeared.join(", ")}`);
+  }
+  if (disappeared.length > 0) {
+    lines.push(`Disappeared: ${disappeared.join(", ")}`);
+  }
+  if (modified.length > 0) {
+    lines.push("Changed:");
+    for (const mod of modified.slice(0, 5)) {
+      lines.push(`  - ${mod.description}: ${mod.property} changed from "${mod.from}" to "${mod.to}"`);
+    }
+    if (modified.length > 5) {
+      lines.push(`  ... and ${modified.length - 5} more changes`);
+    }
+  }
+  if (lines.length === 0) {
+    return "No changes detected";
+  }
+  return lines.join("\n");
+}
+function countElementTypes(elements) {
+  const counts = {};
+  for (const el of elements) {
+    const type = el.type.toLowerCase();
+    counts[type] = (counts[type] || 0) + 1;
+  }
+  return counts;
+}
+function detectForms(elements) {
+  const formElements = elements.filter(
+    (el) => el.type === "input" || el.type === "textarea" || el.type === "select" || el.type === "checkbox"
+  );
+  if (formElements.length === 0) return [];
+  const forms = [];
+  const submitButtons = elements.filter(
+    (el) => el.type === "button" && (el.state.textContent?.toLowerCase().includes("submit") || el.state.textContent?.toLowerCase().includes("save") || el.state.textContent?.toLowerCase().includes("send") || el.semanticType === "submit-button")
+  );
+  const defaultForm = {
+    id: "detected-form",
+    purpose: inferFormPurpose(formElements),
+    fields: formElements.map((el) => ({
+      id: el.id,
+      label: el.labelText || el.accessibleName || el.placeholder || el.id,
+      type: el.type,
+      value: el.state.value || "",
+      valid: true,
+      // Can't determine without validation state
+      required: false,
+      // Can't determine without DOM access
+      placeholder: el.placeholder
+    })),
+    isValid: true,
+    submitButton: submitButtons[0]?.id
+  };
+  if (defaultForm.fields.length > 0) {
+    forms.push(defaultForm);
+  }
+  return forms;
+}
+function inferFormPurpose(fields) {
+  const labels = fields.map(
+    (f) => (f.labelText || f.accessibleName || f.placeholder || "").toLowerCase()
+  );
+  const allLabels = labels.join(" ");
+  if (allLabels.includes("email") && allLabels.includes("password")) {
+    if (allLabels.includes("confirm") || allLabels.includes("name")) {
+      return "Registration form";
+    }
+    return "Login form";
+  }
+  if (allLabels.includes("search")) {
+    return "Search form";
+  }
+  if (allLabels.includes("address") || allLabels.includes("city") || allLabels.includes("zip")) {
+    return "Address form";
+  }
+  if (allLabels.includes("card") || allLabels.includes("cvv") || allLabels.includes("expir")) {
+    return "Payment form";
+  }
+  if (allLabels.includes("contact") || allLabels.includes("message")) {
+    return "Contact form";
+  }
+  return "Form";
+}
+function getKeyElements(elements) {
+  const keyElements = [];
+  const actionButtons = elements.filter(
+    (el) => el.type === "button" && el.state.visible && (el.semanticType?.includes("submit") || el.semanticType?.includes("action") || el.semanticType?.includes("next"))
+  );
+  keyElements.push(...actionButtons.slice(0, 2));
+  const primaryInputs = elements.filter(
+    (el) => (el.type === "input" || el.type === "textarea") && el.state.visible
+  );
+  keyElements.push(...primaryInputs.slice(0, 3));
+  const links = elements.filter((el) => el.type === "link" && el.state.visible);
+  keyElements.push(...links.slice(0, 2));
+  const unique = [...new Map(keyElements.map((e) => [e.id, e])).values()];
+  return unique.slice(0, 8);
+}
+function formatPageType(pageType) {
+  const typeLabels = {
+    login: "Login page",
+    dashboard: "Dashboard",
+    form: "Form page",
+    list: "List/table page",
+    detail: "Detail page",
+    search: "Search page",
+    checkout: "Checkout page",
+    settings: "Settings page",
+    unknown: "Unknown"
+  };
+  return typeLabels[pageType || "unknown"] || "Page";
+}
+function truncate(str, maxLength) {
+  if (str.length <= maxLength) return str;
+  return str.substring(0, maxLength - 3) + "...";
+}
+function inferPageType(url, title, elements) {
+  const urlLower = url.toLowerCase();
+  const titleLower = title.toLowerCase();
+  if (urlLower.includes("login") || urlLower.includes("signin")) return "login";
+  if (urlLower.includes("dashboard")) return "dashboard";
+  if (urlLower.includes("search")) return "search";
+  if (urlLower.includes("checkout") || urlLower.includes("payment")) return "checkout";
+  if (urlLower.includes("settings") || urlLower.includes("preferences")) return "settings";
+  if (titleLower.includes("login") || titleLower.includes("sign in")) return "login";
+  if (titleLower.includes("dashboard")) return "dashboard";
+  if (titleLower.includes("search")) return "search";
+  const hasLoginForm = elements.some((el) => el.type === "input" && el.semanticType === "email-input") && elements.some((el) => el.type === "input" && el.semanticType === "password-input");
+  if (hasLoginForm) return "login";
+  const hasSearchInput = elements.some(
+    (el) => el.type === "input" && el.semanticType === "search-input"
+  );
+  if (hasSearchInput) return "search";
+  const inputCount = elements.filter(
+    (el) => el.type === "input" || el.type === "textarea" || el.type === "select"
+  ).length;
+  if (inputCount >= 3) return "form";
+  const hasTable = elements.some((el) => el.tagName === "table");
+  const hasMany = elements.length > 20;
+  if (hasTable || hasMany) return "list";
+  return "unknown";
+}
+
+// src/ai/nl-action-parser.ts
+var ACTION_PATTERNS = [
+  // Click patterns
+  {
+    regex: /^click\s+(?:on\s+)?(?:the\s+)?(.+?)(?:\s+button)?$/i,
+    action: "click",
+    targetGroup: 1,
+    confidence: 0.95
+  },
+  {
+    regex: /^press\s+(?:the\s+)?(.+?)(?:\s+button)?$/i,
+    action: "click",
+    targetGroup: 1,
+    confidence: 0.9
+  },
+  {
+    regex: /^tap\s+(?:on\s+)?(?:the\s+)?(.+)$/i,
+    action: "click",
+    targetGroup: 1,
+    confidence: 0.85
+  },
+  {
+    regex: /^activate\s+(?:the\s+)?(.+)$/i,
+    action: "click",
+    targetGroup: 1,
+    confidence: 0.8
+  },
+  // Double click patterns
+  {
+    regex: /^double[\s-]?click\s+(?:on\s+)?(?:the\s+)?(.+)$/i,
+    action: "doubleClick",
+    targetGroup: 1,
+    confidence: 0.95
+  },
+  // Right click patterns
+  {
+    regex: /^right[\s-]?click\s+(?:on\s+)?(?:the\s+)?(.+)$/i,
+    action: "rightClick",
+    targetGroup: 1,
+    confidence: 0.95
+  },
+  {
+    regex: /^context\s+click\s+(?:on\s+)?(?:the\s+)?(.+)$/i,
+    action: "rightClick",
+    targetGroup: 1,
+    confidence: 0.9
+  },
+  // Type patterns - "type X in Y"
+  {
+    regex: /^type\s+["'](.+?)["']\s+(?:in(?:to)?|on)\s+(?:the\s+)?(.+)$/i,
+    action: "type",
+    targetGroup: 2,
+    valueGroup: 1,
+    confidence: 0.95
+  },
+  {
+    regex: /^type\s+(.+?)\s+(?:in(?:to)?|on)\s+(?:the\s+)?(.+)$/i,
+    action: "type",
+    targetGroup: 2,
+    valueGroup: 1,
+    confidence: 0.85
+  },
+  // Type patterns - "enter X in Y"
+  {
+    regex: /^enter\s+["'](.+?)["']\s+(?:in(?:to)?|on)\s+(?:the\s+)?(.+)$/i,
+    action: "type",
+    targetGroup: 2,
+    valueGroup: 1,
+    confidence: 0.95
+  },
+  {
+    regex: /^enter\s+(.+?)\s+(?:in(?:to)?|on)\s+(?:the\s+)?(.+)$/i,
+    action: "type",
+    targetGroup: 2,
+    valueGroup: 1,
+    confidence: 0.85
+  },
+  // Type patterns - "input X into Y"
+  {
+    regex: /^input\s+["'](.+?)["']\s+(?:in(?:to)?)\s+(?:the\s+)?(.+)$/i,
+    action: "type",
+    targetGroup: 2,
+    valueGroup: 1,
+    confidence: 0.9
+  },
+  // Type patterns - "fill Y with X"
+  {
+    regex: /^fill\s+(?:in\s+)?(?:the\s+)?(.+?)\s+with\s+["'](.+?)["']$/i,
+    action: "type",
+    targetGroup: 1,
+    valueGroup: 2,
+    confidence: 0.95
+  },
+  {
+    regex: /^fill\s+(?:in\s+)?(?:the\s+)?(.+?)\s+with\s+(.+)$/i,
+    action: "type",
+    targetGroup: 1,
+    valueGroup: 2,
+    confidence: 0.85
+  },
+  // Type patterns - "set Y to X"
+  {
+    regex: /^set\s+(?:the\s+)?(.+?)\s+to\s+["'](.+?)["']$/i,
+    action: "type",
+    targetGroup: 1,
+    valueGroup: 2,
+    confidence: 0.9
+  },
+  // Select patterns
+  {
+    regex: /^select\s+["'](.+?)["']\s+(?:from|in)\s+(?:the\s+)?(.+)$/i,
+    action: "select",
+    targetGroup: 2,
+    valueGroup: 1,
+    confidence: 0.95
+  },
+  {
+    regex: /^choose\s+["'](.+?)["']\s+(?:from|in)\s+(?:the\s+)?(.+)$/i,
+    action: "select",
+    targetGroup: 2,
+    valueGroup: 1,
+    confidence: 0.9
+  },
+  {
+    regex: /^pick\s+["'](.+?)["']\s+(?:from|in)\s+(?:the\s+)?(.+)$/i,
+    action: "select",
+    targetGroup: 2,
+    valueGroup: 1,
+    confidence: 0.85
+  },
+  // Check patterns
+  {
+    regex: /^check\s+(?:the\s+)?(.+?)(?:\s+checkbox)?$/i,
+    action: "check",
+    targetGroup: 1,
+    confidence: 0.9
+  },
+  {
+    regex: /^enable\s+(?:the\s+)?(.+)$/i,
+    action: "check",
+    targetGroup: 1,
+    confidence: 0.8
+  },
+  {
+    regex: /^tick\s+(?:the\s+)?(.+)$/i,
+    action: "check",
+    targetGroup: 1,
+    confidence: 0.85
+  },
+  // Uncheck patterns
+  {
+    regex: /^uncheck\s+(?:the\s+)?(.+?)(?:\s+checkbox)?$/i,
+    action: "uncheck",
+    targetGroup: 1,
+    confidence: 0.9
+  },
+  {
+    regex: /^disable\s+(?:the\s+)?(.+)$/i,
+    action: "uncheck",
+    targetGroup: 1,
+    confidence: 0.8
+  },
+  {
+    regex: /^untick\s+(?:the\s+)?(.+)$/i,
+    action: "uncheck",
+    targetGroup: 1,
+    confidence: 0.85
+  },
+  // Clear patterns
+  {
+    regex: /^clear\s+(?:the\s+)?(.+)$/i,
+    action: "clear",
+    targetGroup: 1,
+    confidence: 0.9
+  },
+  {
+    regex: /^erase\s+(?:the\s+)?(.+)$/i,
+    action: "clear",
+    targetGroup: 1,
+    confidence: 0.85
+  },
+  {
+    regex: /^empty\s+(?:the\s+)?(.+)$/i,
+    action: "clear",
+    targetGroup: 1,
+    confidence: 0.8
+  },
+  // Hover patterns
+  {
+    regex: /^hover\s+(?:over\s+)?(?:the\s+)?(.+)$/i,
+    action: "hover",
+    targetGroup: 1,
+    confidence: 0.9
+  },
+  {
+    regex: /^mouse\s+over\s+(?:the\s+)?(.+)$/i,
+    action: "hover",
+    targetGroup: 1,
+    confidence: 0.85
+  },
+  // Focus patterns
+  {
+    regex: /^focus\s+(?:on\s+)?(?:the\s+)?(.+)$/i,
+    action: "focus",
+    targetGroup: 1,
+    confidence: 0.9
+  },
+  // Scroll patterns
+  {
+    regex: /^scroll\s+(up|down|left|right)$/i,
+    action: "scroll",
+    targetGroup: 1,
+    confidence: 0.9
+  },
+  {
+    regex: /^scroll\s+(?:the\s+)?(.+?)\s+(up|down|left|right)$/i,
+    action: "scroll",
+    targetGroup: 1,
+    confidence: 0.85
+  },
+  {
+    regex: /^scroll\s+to\s+(?:the\s+)?(.+)$/i,
+    action: "scroll",
+    targetGroup: 1,
+    confidence: 0.85
+  },
+  // Wait patterns
+  {
+    regex: /^wait\s+(?:for\s+)?(?:the\s+)?(.+?)(?:\s+to\s+(?:be\s+)?(.+))?$/i,
+    action: "wait",
+    targetGroup: 1,
+    confidence: 0.85
+  },
+  {
+    regex: /^wait\s+until\s+(?:the\s+)?(.+?)(?:\s+(?:is|becomes)\s+(.+))?$/i,
+    action: "wait",
+    targetGroup: 1,
+    confidence: 0.85
+  },
+  // Assert patterns
+  {
+    regex: /^(?:assert|verify|check)\s+(?:that\s+)?(?:the\s+)?(.+?)\s+(?:is\s+)?(visible|hidden|enabled|disabled|checked|unchecked|focused)$/i,
+    action: "assert",
+    targetGroup: 1,
+    confidence: 0.9
+  },
+  {
+    regex: /^(?:assert|verify|check)\s+(?:that\s+)?(?:the\s+)?(.+?)\s+(?:contains|has)\s+["'](.+?)["']$/i,
+    action: "assert",
+    targetGroup: 1,
+    valueGroup: 2,
+    confidence: 0.9
+  },
+  {
+    regex: /^(?:the\s+)?(.+?)\s+should\s+(?:be\s+)?(visible|hidden|enabled|disabled|checked|unchecked|focused)$/i,
+    action: "assert",
+    targetGroup: 1,
+    confidence: 0.85
+  }
+];
+var ASSERTION_TYPE_MAP = {
+  visible: "visible",
+  hidden: "hidden",
+  enabled: "enabled",
+  disabled: "disabled",
+  checked: "checked",
+  unchecked: "unchecked",
+  focused: "focused",
+  contains: "containsText",
+  has: "hasText"
+};
+function parseNLInstruction(instruction) {
+  const trimmed = instruction.trim();
+  if (!trimmed) return null;
+  for (const pattern of ACTION_PATTERNS) {
+    const match = trimmed.match(pattern.regex);
+    if (match) {
+      const parsed = {
+        action: pattern.action,
+        targetDescription: cleanTargetDescription(match[pattern.targetGroup] || ""),
+        rawInstruction: instruction,
+        parseConfidence: pattern.confidence
+      };
+      if (pattern.valueGroup && match[pattern.valueGroup]) {
+        parsed.value = match[pattern.valueGroup];
+      }
+      if (pattern.modifierExtractor) {
+        parsed.modifiers = pattern.modifierExtractor(match);
+      }
+      if (pattern.action === "scroll") {
+        const directionMatch = trimmed.match(/(up|down|left|right)/i);
+        if (directionMatch) {
+          parsed.scrollDirection = directionMatch[1].toLowerCase();
+        }
+      }
+      if (pattern.action === "assert") {
+        const assertMatch = trimmed.match(/(visible|hidden|enabled|disabled|checked|unchecked|focused|contains|has)/i);
+        if (assertMatch) {
+          parsed.assertionType = ASSERTION_TYPE_MAP[assertMatch[1].toLowerCase()];
+        }
+      }
+      if (pattern.action === "wait") {
+        const waitCondition = match[2];
+        if (waitCondition) {
+          parsed.waitCondition = waitCondition;
+        }
+      }
+      return parsed;
+    }
+  }
+  return inferAction(trimmed);
+}
+function cleanTargetDescription(target) {
+  return target.trim().replace(/^(the|a|an)\s+/i, "").replace(/\s+(button|field|input|link|dropdown|checkbox|radio)$/i, "").trim();
+}
+function inferAction(instruction) {
+  const lower = instruction.toLowerCase();
+  if (lower.includes("click") || lower.includes("press") || lower.includes("tap")) {
+    const target = instruction.replace(/click|press|tap|on|the/gi, "").trim();
+    if (target) {
+      return {
+        action: "click",
+        targetDescription: cleanTargetDescription(target),
+        rawInstruction: instruction,
+        parseConfidence: 0.6
+      };
+    }
+  }
+  if (lower.includes("type") || lower.includes("enter") || lower.includes("input")) {
+    const quotedMatch = instruction.match(/["'](.+?)["']/);
+    if (quotedMatch) {
+      const target = instruction.replace(/type|enter|input|into|in|the|["'].*?["']/gi, "").trim();
+      return {
+        action: "type",
+        targetDescription: cleanTargetDescription(target),
+        value: quotedMatch[1],
+        rawInstruction: instruction,
+        parseConfidence: 0.5
+      };
+    }
+  }
+  return null;
+}
+function validateParsedAction(action) {
+  const errors = [];
+  if (!action.targetDescription && action.action !== "scroll") {
+    errors.push("No target element specified");
+  }
+  if ((action.action === "type" || action.action === "select") && !action.value) {
+    errors.push(`No value specified for ${action.action} action`);
+  }
+  if (action.parseConfidence < 0.5) {
+    errors.push("Low confidence parsing - instruction may be ambiguous");
+  }
+  return {
+    valid: errors.length === 0,
+    errors
+  };
+}
+function describeAction(action) {
+  switch (action.action) {
+    case "click":
+      return `Click on "${action.targetDescription}"`;
+    case "doubleClick":
+      return `Double-click on "${action.targetDescription}"`;
+    case "rightClick":
+      return `Right-click on "${action.targetDescription}"`;
+    case "type":
+      return `Type "${action.value}" into "${action.targetDescription}"`;
+    case "select":
+      return `Select "${action.value}" from "${action.targetDescription}"`;
+    case "check":
+      return `Check "${action.targetDescription}"`;
+    case "uncheck":
+      return `Uncheck "${action.targetDescription}"`;
+    case "clear":
+      return `Clear "${action.targetDescription}"`;
+    case "hover":
+      return `Hover over "${action.targetDescription}"`;
+    case "focus":
+      return `Focus on "${action.targetDescription}"`;
+    case "scroll":
+      if (action.scrollDirection) {
+        return `Scroll ${action.scrollDirection}`;
+      }
+      return `Scroll to "${action.targetDescription}"`;
+    case "wait":
+      return `Wait for "${action.targetDescription}"${action.waitCondition ? ` to be ${action.waitCondition}` : ""}`;
+    case "assert":
+      return `Assert "${action.targetDescription}" is ${action.assertionType || "valid"}`;
+    default:
+      return `${action.action} on "${action.targetDescription}"`;
+  }
+}
+
+// src/ai/error-context.ts
+function getElementState(el) {
+  if ("state" in el && el.state) {
+    return el.state;
+  }
+  if ("getState" in el && typeof el.getState === "function") {
+    try {
+      return el.getState();
+    } catch {
+      return void 0;
+    }
+  }
+  return void 0;
+}
+var ERROR_MESSAGES = {
+  PARSE_ERROR: "Could not parse the natural language instruction",
+  VALIDATION_ERROR: "The parsed action failed validation",
+  ELEMENT_NOT_FOUND: "No element matching the description could be found",
+  ELEMENT_NOT_VISIBLE: "The element exists but is not visible",
+  ELEMENT_DISABLED: "The element is disabled and cannot be interacted with",
+  ELEMENT_BLOCKED: "The element is blocked by another element",
+  MULTIPLE_ELEMENTS: "Multiple elements match the description",
+  LOW_CONFIDENCE: "The best match has low confidence",
+  AMBIGUOUS_MATCH: "Multiple elements match with similar confidence",
+  ACTION_FAILED: "The action could not be completed",
+  ACTION_TIMEOUT: "The action timed out waiting for a condition",
+  UNSUPPORTED_ACTION: "The requested action is not supported",
+  UNEXPECTED_STATE: "The element is in an unexpected state",
+  STALE_ELEMENT: "The element is no longer attached to the DOM",
+  PAGE_LOAD_ERROR: "The page failed to load correctly",
+  NAVIGATION_ERROR: "Navigation to the target page failed"
+};
+var ERROR_SUGGESTIONS = {
+  PARSE_ERROR: [
+    {
+      action: 'Use a simpler instruction format like "click Submit button"',
+      confidence: 0.8,
+      priority: 1
+    },
+    {
+      action: "Use specific element names visible on the page",
+      confidence: 0.7,
+      priority: 2
+    }
+  ],
+  VALIDATION_ERROR: [
+    {
+      action: "Provide required parameters for the action",
+      confidence: 0.9,
+      priority: 1
+    },
+    {
+      action: "Check the instruction format",
+      confidence: 0.7,
+      priority: 2
+    }
+  ],
+  ELEMENT_NOT_FOUND: [
+    {
+      action: "Wait for the page to fully load",
+      command: "wait for page to load",
+      confidence: 0.7,
+      priority: 1
+    },
+    {
+      action: "Use a different description for the element",
+      confidence: 0.8,
+      priority: 2
+    },
+    {
+      action: "Scroll the page to reveal the element",
+      command: "scroll down",
+      confidence: 0.6,
+      priority: 3
+    }
+  ],
+  ELEMENT_NOT_VISIBLE: [
+    {
+      action: "Scroll to make the element visible",
+      command: "scroll to element",
+      confidence: 0.9,
+      priority: 1
+    },
+    {
+      action: "Close any overlaying elements",
+      confidence: 0.7,
+      priority: 2
+    },
+    {
+      action: "Wait for loading to complete",
+      command: "wait for loading",
+      confidence: 0.6,
+      priority: 3
+    }
+  ],
+  ELEMENT_DISABLED: [
+    {
+      action: "Fill in required fields first",
+      confidence: 0.8,
+      priority: 1
+    },
+    {
+      action: "Complete prerequisite steps",
+      confidence: 0.7,
+      priority: 2
+    },
+    {
+      action: "Wait for the element to become enabled",
+      command: "wait for element to be enabled",
+      confidence: 0.6,
+      priority: 3
+    }
+  ],
+  ELEMENT_BLOCKED: [
+    {
+      action: "Close the modal or popup",
+      command: "click close button",
+      confidence: 0.9,
+      priority: 1
+    },
+    {
+      action: "Dismiss the overlay",
+      confidence: 0.8,
+      priority: 2
+    },
+    {
+      action: "Wait for the blocking element to disappear",
+      confidence: 0.6,
+      priority: 3
+    }
+  ],
+  MULTIPLE_ELEMENTS: [
+    {
+      action: "Use a more specific description",
+      confidence: 0.9,
+      priority: 1
+    },
+    {
+      action: "Include the element position (first, second, etc.)",
+      confidence: 0.8,
+      priority: 2
+    },
+    {
+      action: "Use the element ID directly",
+      confidence: 0.7,
+      priority: 3
+    }
+  ],
+  LOW_CONFIDENCE: [
+    {
+      action: "Use the exact text shown on the element",
+      confidence: 0.9,
+      priority: 1
+    },
+    {
+      action: "Lower the confidence threshold if the match is correct",
+      confidence: 0.7,
+      priority: 2
+    },
+    {
+      action: "Try a different way to describe the element",
+      confidence: 0.6,
+      priority: 3
+    }
+  ],
+  AMBIGUOUS_MATCH: [
+    {
+      action: "Be more specific about which element you mean",
+      confidence: 0.9,
+      priority: 1
+    },
+    {
+      action: "Include the section or form name",
+      confidence: 0.8,
+      priority: 2
+    }
+  ],
+  ACTION_FAILED: [
+    {
+      action: "Check if the element is interactable",
+      confidence: 0.7,
+      priority: 1
+    },
+    {
+      action: "Wait and retry the action",
+      command: "wait 1 second then retry",
+      confidence: 0.6,
+      priority: 2
+    }
+  ],
+  ACTION_TIMEOUT: [
+    {
+      action: "Increase the timeout duration",
+      confidence: 0.8,
+      priority: 1
+    },
+    {
+      action: "Check if the condition can ever be met",
+      confidence: 0.7,
+      priority: 2
+    }
+  ],
+  UNSUPPORTED_ACTION: [
+    {
+      action: "Use a different action type",
+      confidence: 0.9,
+      priority: 1
+    },
+    {
+      action: "Break down into simpler actions",
+      confidence: 0.7,
+      priority: 2
+    }
+  ],
+  UNEXPECTED_STATE: [
+    {
+      action: "Refresh the page state",
+      command: "refresh",
+      confidence: 0.7,
+      priority: 1
+    },
+    {
+      action: "Wait for state to stabilize",
+      command: "wait 2 seconds",
+      confidence: 0.6,
+      priority: 2
+    }
+  ],
+  STALE_ELEMENT: [
+    {
+      action: "Re-find the element",
+      confidence: 0.9,
+      priority: 1
+    },
+    {
+      action: "Wait for page to stabilize",
+      command: "wait 1 second",
+      confidence: 0.7,
+      priority: 2
+    }
+  ],
+  PAGE_LOAD_ERROR: [
+    {
+      action: "Refresh the page",
+      command: "refresh page",
+      confidence: 0.8,
+      priority: 1
+    },
+    {
+      action: "Check network connectivity",
+      confidence: 0.6,
+      priority: 2
+    }
+  ],
+  NAVIGATION_ERROR: [
+    {
+      action: "Try the navigation again",
+      confidence: 0.7,
+      priority: 1
+    },
+    {
+      action: "Check if the URL is correct",
+      confidence: 0.6,
+      priority: 2
+    }
+  ]
+};
+function createErrorContext(errorCode, attemptedAction, availableElements, searchCriteria, nearestMatch) {
+  const message = ERROR_MESSAGES[errorCode] || "An unknown error occurred";
+  const baseSuggestions = ERROR_SUGGESTIONS[errorCode] || [];
+  const possibleBlockers = detectPossibleBlockers(availableElements);
+  const visibleElements = availableElements.filter((el) => {
+    const state = getElementState(el);
+    return state?.visible ?? false;
+  }).length;
+  const suggestions = enhanceSuggestions(
+    baseSuggestions,
+    errorCode,
+    nearestMatch,
+    possibleBlockers
+  );
+  return {
+    code: errorCode,
+    message,
+    attemptedAction,
+    searchCriteria,
+    searchResults: {
+      candidatesFound: availableElements.length,
+      nearestMatch: nearestMatch ? {
+        element: nearestMatch.element,
+        confidence: nearestMatch.confidence,
+        whyNotSelected: determineWhyNotSelected(errorCode, nearestMatch)
+      } : void 0
+    },
+    pageContext: {
+      url: typeof window !== "undefined" ? window.location.href : "",
+      title: typeof document !== "undefined" ? document.title : "",
+      visibleElements,
+      possibleBlockers
+    },
+    suggestions,
+    timestamp: Date.now()
+  };
+}
+function detectPossibleBlockers(elements) {
+  const blockers = [];
+  for (const el of elements) {
+    const state = getElementState(el);
+    if (!state) continue;
+    if (el.type === "dialog" && state.visible) {
+      blockers.push(`Modal dialog: ${el.id}`);
+    }
+    if (state.computedStyles?.pointerEvents === "none") {
+      continue;
+    }
+  }
+  return blockers;
+}
+function enhanceSuggestions(baseSuggestions, errorCode, nearestMatch, possibleBlockers) {
+  const suggestions = [...baseSuggestions];
+  if (possibleBlockers && possibleBlockers.length > 0) {
+    suggestions.unshift({
+      action: `Close the blocking element: ${possibleBlockers[0]}`,
+      command: "click close button",
+      confidence: 0.85,
+      priority: 0
+    });
+  }
+  if (nearestMatch && errorCode === "LOW_CONFIDENCE") {
+    suggestions.unshift({
+      action: `Did you mean: "${nearestMatch.element.description}"?`,
+      command: `click "${nearestMatch.element.description}"`,
+      confidence: nearestMatch.confidence,
+      priority: 0
+    });
+  }
+  suggestions.sort((a, b) => a.priority - b.priority);
+  return suggestions;
+}
+function determineWhyNotSelected(errorCode, nearestMatch) {
+  switch (errorCode) {
+    case "LOW_CONFIDENCE":
+      return `Confidence (${(nearestMatch.confidence * 100).toFixed(0)}%) below threshold`;
+    case "ELEMENT_NOT_VISIBLE":
+      return "Element is not visible";
+    case "ELEMENT_DISABLED":
+      return "Element is disabled";
+    case "AMBIGUOUS_MATCH":
+      return "Multiple elements with similar confidence";
+    default:
+      return "Did not meet selection criteria";
+  }
+}
+
+// src/ai/nl-action-executor.ts
+var DEFAULT_EXECUTOR_CONFIG = {
+  defaultConfidenceThreshold: 0.7,
+  defaultTimeout: 5e3,
+  maxAlternatives: 3,
+  verbose: false
+};
+var NLActionExecutor = class {
+  constructor(config = {}) {
+    this.actionExecutor = null;
+    this.elements = [];
+    this.config = { ...DEFAULT_EXECUTOR_CONFIG, ...config };
+    this.searchEngine = new SearchEngine(this.config.searchConfig);
+  }
+  /**
+   * Set the action executor for performing DOM actions
+   */
+  setActionExecutor(executor) {
+    this.actionExecutor = executor;
+  }
+  /**
+   * Update available elements for search
+   */
+  updateElements(elements) {
+    this.elements = elements;
+    this.searchEngine.updateElements(elements);
+  }
+  /**
+   * Execute a natural language instruction
+   */
+  async execute(request) {
+    const startTime = performance.now();
+    const threshold = request.confidenceThreshold ?? this.config.defaultConfidenceThreshold;
+    const parsed = parseNLInstruction(request.instruction);
+    if (!parsed) {
+      return this.createFailureResponse(
+        startTime,
+        "PARSE_ERROR",
+        `Could not parse instruction: "${request.instruction}"`,
+        request.instruction,
+        [],
+        threshold
+      );
+    }
+    const validation = validateParsedAction(parsed);
+    if (!validation.valid) {
+      return this.createFailureResponse(
+        startTime,
+        "VALIDATION_ERROR",
+        validation.errors.join("; "),
+        request.instruction,
+        [],
+        threshold
+      );
+    }
+    const searchCriteria = this.buildSearchCriteria(parsed);
+    const searchResponse = this.searchEngine.search(searchCriteria);
+    if (!searchResponse.bestMatch) {
+      return this.createFailureResponse(
+        startTime,
+        "ELEMENT_NOT_FOUND",
+        `Could not find element matching: "${parsed.targetDescription}"`,
+        request.instruction,
+        searchResponse.results,
+        threshold,
+        searchCriteria
+      );
+    }
+    if (searchResponse.bestMatch.confidence < threshold) {
+      const alternatives = searchResponse.results.slice(0, this.config.maxAlternatives);
+      return this.createFailureResponse(
+        startTime,
+        "LOW_CONFIDENCE",
+        `Best match confidence (${(searchResponse.bestMatch.confidence * 100).toFixed(0)}%) is below threshold (${(threshold * 100).toFixed(0)}%)`,
+        request.instruction,
+        alternatives,
+        threshold,
+        searchCriteria,
+        searchResponse.bestMatch
+      );
+    }
+    try {
+      const result = await this.performAction(
+        parsed,
+        searchResponse.bestMatch.element,
+        request.timeout ?? this.config.defaultTimeout
+      );
+      return {
+        success: true,
+        executedAction: describeAction(parsed),
+        elementUsed: searchResponse.bestMatch.element,
+        confidence: searchResponse.bestMatch.confidence,
+        elementState: result.elementState,
+        durationMs: performance.now() - startTime,
+        timestamp: Date.now()
+      };
+    } catch (error2) {
+      const errorMessage = error2 instanceof Error ? error2.message : String(error2);
+      const alternatives = searchResponse.results.filter((r) => r !== searchResponse.bestMatch).slice(0, this.config.maxAlternatives);
+      return this.createFailureResponse(
+        startTime,
+        "ACTION_FAILED",
+        errorMessage,
+        request.instruction,
+        alternatives,
+        threshold,
+        searchCriteria,
+        searchResponse.bestMatch
+      );
+    }
+  }
+  /**
+   * Execute a parsed action directly (skip parsing)
+   */
+  async executeParsed(parsed, threshold) {
+    const startTime = performance.now();
+    const confidenceThreshold = threshold ?? this.config.defaultConfidenceThreshold;
+    const searchCriteria = this.buildSearchCriteria(parsed);
+    const searchResponse = this.searchEngine.search(searchCriteria);
+    if (!searchResponse.bestMatch) {
+      return this.createFailureResponse(
+        startTime,
+        "ELEMENT_NOT_FOUND",
+        `Could not find element: "${parsed.targetDescription}"`,
+        parsed.rawInstruction,
+        [],
+        confidenceThreshold,
+        searchCriteria
+      );
+    }
+    if (searchResponse.bestMatch.confidence < confidenceThreshold) {
+      return this.createFailureResponse(
+        startTime,
+        "LOW_CONFIDENCE",
+        `Best match confidence too low`,
+        parsed.rawInstruction,
+        searchResponse.results.slice(0, this.config.maxAlternatives),
+        confidenceThreshold,
+        searchCriteria,
+        searchResponse.bestMatch
+      );
+    }
+    try {
+      const result = await this.performAction(
+        parsed,
+        searchResponse.bestMatch.element,
+        this.config.defaultTimeout
+      );
+      return {
+        success: true,
+        executedAction: describeAction(parsed),
+        elementUsed: searchResponse.bestMatch.element,
+        confidence: searchResponse.bestMatch.confidence,
+        elementState: result.elementState,
+        durationMs: performance.now() - startTime,
+        timestamp: Date.now()
+      };
+    } catch (error2) {
+      return this.createFailureResponse(
+        startTime,
+        "ACTION_FAILED",
+        error2 instanceof Error ? error2.message : String(error2),
+        parsed.rawInstruction,
+        searchResponse.results.filter((r) => r !== searchResponse.bestMatch).slice(0, this.config.maxAlternatives),
+        confidenceThreshold,
+        searchCriteria,
+        searchResponse.bestMatch
+      );
+    }
+  }
+  /**
+   * Build search criteria from a parsed action
+   */
+  buildSearchCriteria(parsed) {
+    const criteria = {
+      text: parsed.targetDescription,
+      fuzzy: true,
+      fuzzyThreshold: this.config.defaultConfidenceThreshold
+    };
+    switch (parsed.action) {
+      case "click":
+      case "doubleClick":
+      case "rightClick":
+        break;
+      case "type":
+      case "clear":
+        criteria.type = "input";
+        break;
+      case "select":
+        criteria.type = "select";
+        break;
+      case "check":
+      case "uncheck":
+        criteria.type = "checkbox";
+        break;
+    }
+    return criteria;
+  }
+  /**
+   * Perform the actual action on an element
+   */
+  async performAction(parsed, element, timeout) {
+    if (!this.actionExecutor) {
+      throw new Error("No action executor configured");
+    }
+    const actionMap = {
+      click: "click",
+      doubleClick: "doubleClick",
+      rightClick: "rightClick",
+      type: "type",
+      select: "select",
+      check: "check",
+      uncheck: "uncheck",
+      scroll: "scroll",
+      wait: null,
+      // Special handling
+      assert: null,
+      // Special handling
+      hover: "hover",
+      focus: "focus",
+      clear: "clear"
+    };
+    const standardAction = actionMap[parsed.action];
+    if (!standardAction) {
+      if (parsed.action === "wait") {
+        const waitResult = await this.actionExecutor.waitFor(element.id, {
+          visible: true,
+          timeout
+        });
+        if (!waitResult.met) {
+          throw new Error(waitResult.error || "Wait condition not met");
+        }
+        return { elementState: waitResult.state };
+      }
+      if (parsed.action === "assert") {
+        throw new Error("Use the assertions module for assert actions");
+      }
+      throw new Error(`Unsupported action: ${parsed.action}`);
+    }
+    const actionRequest = {
+      action: standardAction,
+      waitOptions: {
+        visible: true,
+        enabled: true,
+        timeout
+      }
+    };
+    if (standardAction === "type" && parsed.value) {
+      actionRequest.params = { text: parsed.value };
+    } else if (standardAction === "select" && parsed.value) {
+      actionRequest.params = { value: parsed.value };
+    } else if (standardAction === "scroll" && parsed.scrollDirection) {
+      actionRequest.params = { direction: parsed.scrollDirection };
+    }
+    const response = await this.actionExecutor.executeAction(element.id, actionRequest);
+    if (!response.success) {
+      throw new Error(response.error || "Action failed");
+    }
+    return { elementState: response.elementState };
+  }
+  /**
+   * Create a failure response with suggestions
+   */
+  createFailureResponse(startTime, errorCode, errorMessage, instruction, alternatives, threshold, searchCriteria, nearestMatch) {
+    const suggestions = this.generateSuggestions(
+      errorCode,
+      instruction,
+      alternatives,
+      nearestMatch
+    );
+    const dummyElement = nearestMatch?.element || {
+      id: "not-found",
+      type: "unknown",
+      tagName: "unknown",
+      actions: [],
+      state: {
+        visible: false,
+        enabled: false,
+        focused: false,
+        rect: { x: 0, y: 0, width: 0, height: 0, top: 0, right: 0, bottom: 0, left: 0 }
+      },
+      registered: false,
+      description: "Element not found",
+      aliases: [],
+      suggestedActions: []
+    };
+    return {
+      success: false,
+      executedAction: instruction,
+      elementUsed: dummyElement,
+      confidence: nearestMatch?.confidence || 0,
+      elementState: dummyElement.state,
+      durationMs: performance.now() - startTime,
+      timestamp: Date.now(),
+      error: errorMessage,
+      errorCode,
+      suggestions,
+      alternatives: alternatives.slice(0, this.config.maxAlternatives)
+    };
+  }
+  /**
+   * Generate recovery suggestions
+   */
+  generateSuggestions(errorCode, instruction, alternatives, nearestMatch) {
+    const suggestions = [];
+    switch (errorCode) {
+      case "PARSE_ERROR":
+        suggestions.push('Try using a simpler phrase like "click Submit button"');
+        suggestions.push('Ensure the instruction follows patterns like "click X" or "type Y into X"');
+        break;
+      case "ELEMENT_NOT_FOUND":
+        if (alternatives.length > 0) {
+          suggestions.push(`Did you mean: "${alternatives[0].element.description}"?`);
+        }
+        suggestions.push("Check if the element is visible on the page");
+        suggestions.push("Try using a more specific description");
+        break;
+      case "LOW_CONFIDENCE":
+        if (nearestMatch) {
+          suggestions.push(
+            `Found "${nearestMatch.element.description}" with ${(nearestMatch.confidence * 100).toFixed(0)}% confidence`
+          );
+        }
+        suggestions.push("Try using the exact text shown on the element");
+        suggestions.push("Lower the confidence threshold if this match is correct");
+        break;
+      case "ACTION_FAILED":
+        suggestions.push("Check if the element is enabled");
+        suggestions.push("Wait for any loading to complete");
+        suggestions.push("Ensure no modal or overlay is blocking the element");
+        break;
+      default:
+        suggestions.push("Try a different approach or check the page state");
+    }
+    return suggestions;
+  }
+  /**
+   * Get rich error context for debugging
+   */
+  getErrorContext(errorCode, instruction, searchCriteria, nearestMatch) {
+    return createErrorContext(
+      errorCode,
+      instruction,
+      this.elements,
+      searchCriteria,
+      nearestMatch
+    );
+  }
+};
+
+// src/ai/assertions.ts
+var DEFAULT_ASSERTION_CONFIG = {
+  defaultTimeout: 5e3,
+  pollInterval: 100,
+  fuzzyThreshold: 0.7,
+  includeSuggestions: true
+};
+var AssertionExecutor = class {
+  constructor(config = {}) {
+    this.elements = [];
+    this.config = { ...DEFAULT_ASSERTION_CONFIG, ...config };
+    this.searchEngine = new SearchEngine({ fuzzyThreshold: this.config.fuzzyThreshold });
+  }
+  /**
+   * Update available elements for assertions
+   */
+  updateElements(elements) {
+    this.elements = elements;
+    this.searchEngine.updateElements(elements);
+  }
+  /**
+   * Execute a single assertion
+   */
+  async assert(request) {
+    const startTime = performance.now();
+    const timeout = request.timeout ?? this.config.defaultTimeout;
+    const element = await this.findElement(request.target, request.fuzzy !== false);
+    if (!element && request.type !== "notExists") {
+      return this.createResult(
+        false,
+        typeof request.target === "string" ? request.target : JSON.stringify(request.target),
+        "element not found",
+        request.type === "exists" ? true : request.expected,
+        null,
+        "Element could not be found",
+        this.config.includeSuggestions ? "Check if the element exists and is properly labeled" : void 0,
+        startTime
+      );
+    }
+    return this.executeAssertion(request, element, timeout, startTime);
+  }
+  /**
+   * Execute multiple assertions
+   */
+  async assertBatch(request) {
+    const startTime = performance.now();
+    const results = [];
+    let passedCount = 0;
+    let failedCount = 0;
+    for (const assertion of request.assertions) {
+      const result = await this.assert(assertion);
+      results.push(result);
+      if (result.passed) {
+        passedCount++;
+      } else {
+        failedCount++;
+        if (request.stopOnFailure) {
+          break;
+        }
+      }
+    }
+    const passed = request.mode === "all" ? failedCount === 0 : passedCount > 0;
+    return {
+      passed,
+      results,
+      passedCount,
+      failedCount,
+      durationMs: performance.now() - startTime,
+      timestamp: Date.now()
+    };
+  }
+  /**
+   * Convenience method: assert element is visible
+   */
+  async assertVisible(target, timeout) {
+    return this.assert({ target, type: "visible", timeout });
+  }
+  /**
+   * Convenience method: assert element is hidden
+   */
+  async assertHidden(target, timeout) {
+    return this.assert({ target, type: "hidden", timeout });
+  }
+  /**
+   * Convenience method: assert element is enabled
+   */
+  async assertEnabled(target, timeout) {
+    return this.assert({ target, type: "enabled", timeout });
+  }
+  /**
+   * Convenience method: assert element is disabled
+   */
+  async assertDisabled(target, timeout) {
+    return this.assert({ target, type: "disabled", timeout });
+  }
+  /**
+   * Convenience method: assert element has text
+   */
+  async assertHasText(target, text, timeout) {
+    return this.assert({ target, type: "hasText", expected: text, timeout });
+  }
+  /**
+   * Convenience method: assert element contains text
+   */
+  async assertContainsText(target, text, timeout) {
+    return this.assert({ target, type: "containsText", expected: text, timeout });
+  }
+  /**
+   * Convenience method: assert element has value
+   */
+  async assertHasValue(target, value, timeout) {
+    return this.assert({ target, type: "hasValue", expected: value, timeout });
+  }
+  /**
+   * Convenience method: assert element exists
+   */
+  async assertExists(target, timeout) {
+    return this.assert({ target, type: "exists", timeout });
+  }
+  /**
+   * Convenience method: assert element does not exist
+   */
+  async assertNotExists(target, timeout) {
+    return this.assert({ target, type: "notExists", timeout });
+  }
+  /**
+   * Convenience method: assert checkbox is checked
+   */
+  async assertChecked(target, timeout) {
+    return this.assert({ target, type: "checked", timeout });
+  }
+  /**
+   * Convenience method: assert checkbox is unchecked
+   */
+  async assertUnchecked(target, timeout) {
+    return this.assert({ target, type: "unchecked", timeout });
+  }
+  /**
+   * Convenience method: assert element count
+   */
+  async assertCount(target, expectedCount, timeout) {
+    return this.assert({ target, type: "count", expected: expectedCount, timeout });
+  }
+  /**
+   * Find element by target (string or criteria)
+   */
+  async findElement(target, fuzzy = true) {
+    const criteria = typeof target === "string" ? { text: target, fuzzy } : { ...target, fuzzy };
+    const searchResult = this.searchEngine.findBest(criteria);
+    if (searchResult && searchResult.confidence >= this.config.fuzzyThreshold) {
+      return searchResult.element;
+    }
+    return null;
+  }
+  /**
+   * Execute the actual assertion
+   */
+  async executeAssertion(request, element, timeout, startTime) {
+    const targetStr = typeof request.target === "string" ? request.target : JSON.stringify(request.target);
+    const elementDescription = element?.description || targetStr;
+    switch (request.type) {
+      case "visible":
+        return this.assertVisibility(element, true, elementDescription, request.message, startTime);
+      case "hidden":
+        return this.assertVisibility(element, false, elementDescription, request.message, startTime);
+      case "enabled":
+        return this.assertEnabledState(element, true, elementDescription, request.message, startTime);
+      case "disabled":
+        return this.assertEnabledState(element, false, elementDescription, request.message, startTime);
+      case "focused":
+        return this.assertFocused(element, elementDescription, request.message, startTime);
+      case "checked":
+        return this.assertCheckedState(element, true, elementDescription, request.message, startTime);
+      case "unchecked":
+        return this.assertCheckedState(element, false, elementDescription, request.message, startTime);
+      case "hasText":
+        return this.assertTextMatch(
+          element,
+          request.expected,
+          true,
+          elementDescription,
+          request.message,
+          startTime
+        );
+      case "containsText":
+        return this.assertTextMatch(
+          element,
+          request.expected,
+          false,
+          elementDescription,
+          request.message,
+          startTime
+        );
+      case "hasValue":
+        return this.assertValue(
+          element,
+          request.expected,
+          elementDescription,
+          request.message,
+          startTime
+        );
+      case "exists":
+        return this.createResult(
+          element !== null,
+          targetStr,
+          elementDescription,
+          true,
+          element !== null,
+          element === null ? "Element does not exist" : void 0,
+          void 0,
+          startTime,
+          element?.state
+        );
+      case "notExists":
+        return this.createResult(
+          element === null,
+          targetStr,
+          elementDescription,
+          false,
+          element === null,
+          element !== null ? "Element exists but should not" : void 0,
+          void 0,
+          startTime,
+          element?.state
+        );
+      case "count":
+        return this.assertElementCount(
+          request.target,
+          request.expected,
+          targetStr,
+          request.message,
+          startTime
+        );
+      case "attribute":
+        return this.assertAttribute(
+          element,
+          request.attributeName,
+          request.expected,
+          elementDescription,
+          request.message,
+          startTime
+        );
+      case "hasClass":
+        return this.assertHasClass(
+          element,
+          request.expected,
+          elementDescription,
+          request.message,
+          startTime
+        );
+      case "cssProperty":
+        return this.assertCssProperty(
+          element,
+          request.propertyName,
+          request.expected,
+          elementDescription,
+          request.message,
+          startTime
+        );
+      default:
+        return this.createResult(
+          false,
+          targetStr,
+          elementDescription,
+          void 0,
+          void 0,
+          `Unknown assertion type: ${request.type}`,
+          void 0,
+          startTime
+        );
+    }
+  }
+  /**
+   * Assert visibility state
+   */
+  assertVisibility(element, expectedVisible, description, message, startTime = performance.now()) {
+    const isVisible = element.state.visible;
+    const passed = isVisible === expectedVisible;
+    return this.createResult(
+      passed,
+      element.id,
+      description,
+      expectedVisible,
+      isVisible,
+      passed ? void 0 : message || `Element is ${isVisible ? "visible" : "hidden"} but expected ${expectedVisible ? "visible" : "hidden"}`,
+      passed ? void 0 : "Check if element is covered by another element or has display:none",
+      startTime,
+      element.state
+    );
+  }
+  /**
+   * Assert enabled state
+   */
+  assertEnabledState(element, expectedEnabled, description, message, startTime = performance.now()) {
+    const isEnabled = element.state.enabled;
+    const passed = isEnabled === expectedEnabled;
+    return this.createResult(
+      passed,
+      element.id,
+      description,
+      expectedEnabled,
+      isEnabled,
+      passed ? void 0 : message || `Element is ${isEnabled ? "enabled" : "disabled"} but expected ${expectedEnabled ? "enabled" : "disabled"}`,
+      passed ? void 0 : "Check if the element has a disabled attribute or aria-disabled",
+      startTime,
+      element.state
+    );
+  }
+  /**
+   * Assert focused state
+   */
+  assertFocused(element, description, message, startTime = performance.now()) {
+    const isFocused = element.state.focused;
+    return this.createResult(
+      isFocused,
+      element.id,
+      description,
+      true,
+      isFocused,
+      isFocused ? void 0 : message || "Element is not focused",
+      isFocused ? void 0 : "Click or focus the element first",
+      startTime,
+      element.state
+    );
+  }
+  /**
+   * Assert checked state
+   */
+  assertCheckedState(element, expectedChecked, description, message, startTime = performance.now()) {
+    const isChecked = element.state.checked ?? false;
+    const passed = isChecked === expectedChecked;
+    return this.createResult(
+      passed,
+      element.id,
+      description,
+      expectedChecked,
+      isChecked,
+      passed ? void 0 : message || `Element is ${isChecked ? "checked" : "unchecked"} but expected ${expectedChecked ? "checked" : "unchecked"}`,
+      passed ? void 0 : "Click the checkbox to change its state",
+      startTime,
+      element.state
+    );
+  }
+  /**
+   * Assert text content
+   */
+  assertTextMatch(element, expectedText, exact, description, message, startTime = performance.now()) {
+    const actualText = element.state.textContent || "";
+    const passed = exact ? actualText === expectedText : actualText.includes(expectedText);
+    return this.createResult(
+      passed,
+      element.id,
+      description,
+      expectedText,
+      actualText,
+      passed ? void 0 : message || (exact ? `Text "${actualText}" does not match expected "${expectedText}"` : `Text "${actualText}" does not contain "${expectedText}"`),
+      passed ? void 0 : "Verify the element contains the expected text",
+      startTime,
+      element.state
+    );
+  }
+  /**
+   * Assert input value
+   */
+  assertValue(element, expectedValue, description, message, startTime = performance.now()) {
+    const actualValue = element.state.value || "";
+    const passed = actualValue === expectedValue;
+    return this.createResult(
+      passed,
+      element.id,
+      description,
+      expectedValue,
+      actualValue,
+      passed ? void 0 : message || `Value "${actualValue}" does not match expected "${expectedValue}"`,
+      passed ? void 0 : "Type the expected value into the input",
+      startTime,
+      element.state
+    );
+  }
+  /**
+   * Assert element count
+   */
+  assertElementCount(criteria, expectedCount, targetStr, message, startTime = performance.now()) {
+    const searchResponse = this.searchEngine.search(criteria);
+    const actualCount = searchResponse.results.length;
+    const passed = actualCount === expectedCount;
+    return this.createResult(
+      passed,
+      targetStr,
+      `${actualCount} elements matching criteria`,
+      expectedCount,
+      actualCount,
+      passed ? void 0 : message || `Found ${actualCount} elements but expected ${expectedCount}`,
+      passed ? void 0 : "Adjust search criteria or wait for elements to load",
+      startTime
+    );
+  }
+  /**
+   * Assert attribute value (placeholder for DOM attribute assertions)
+   */
+  assertAttribute(element, attributeName, expectedValue, description, message, startTime = performance.now()) {
+    let actualValue;
+    switch (attributeName.toLowerCase()) {
+      case "placeholder":
+        actualValue = element.placeholder;
+        break;
+      case "title":
+        actualValue = element.title;
+        break;
+      default:
+        return this.createResult(
+          false,
+          element.id,
+          description,
+          expectedValue,
+          void 0,
+          `Cannot check attribute "${attributeName}" without DOM access`,
+          "Use the server API to check element attributes",
+          startTime,
+          element.state
+        );
+    }
+    const passed = actualValue === expectedValue;
+    return this.createResult(
+      passed,
+      element.id,
+      description,
+      expectedValue,
+      actualValue,
+      passed ? void 0 : message || `Attribute "${attributeName}" is "${actualValue}" but expected "${expectedValue}"`,
+      void 0,
+      startTime,
+      element.state
+    );
+  }
+  /**
+   * Assert element has CSS class
+   */
+  assertHasClass(element, className, description, message, startTime = performance.now()) {
+    return this.createResult(
+      false,
+      element.id,
+      description,
+      className,
+      void 0,
+      "Cannot check CSS classes without DOM access",
+      "Use the server API to check element classes",
+      startTime,
+      element.state
+    );
+  }
+  /**
+   * Assert CSS property value
+   */
+  assertCssProperty(element, propertyName, expectedValue, description, message, startTime = performance.now()) {
+    const computedStyles = element.state.computedStyles;
+    if (!computedStyles) {
+      return this.createResult(
+        false,
+        element.id,
+        description,
+        expectedValue,
+        void 0,
+        "Computed styles not available",
+        "Request element state with computed styles",
+        startTime,
+        element.state
+      );
+    }
+    const styleKey = propertyName;
+    const actualValue = computedStyles[styleKey];
+    const passed = actualValue === expectedValue;
+    return this.createResult(
+      passed,
+      element.id,
+      description,
+      expectedValue,
+      actualValue,
+      passed ? void 0 : message || `CSS property "${propertyName}" is "${actualValue}" but expected "${expectedValue}"`,
+      void 0,
+      startTime,
+      element.state
+    );
+  }
+  /**
+   * Create an assertion result
+   */
+  createResult(passed, target, targetDescription, expected, actual, failureReason, suggestion, startTime = performance.now(), elementState) {
+    return {
+      passed,
+      target,
+      targetDescription,
+      expected,
+      actual,
+      failureReason,
+      suggestion: this.config.includeSuggestions ? suggestion : void 0,
+      elementState,
+      durationMs: performance.now() - startTime,
+      timestamp: Date.now()
+    };
+  }
+};
+
+// src/ai/semantic-snapshot.ts
+var DEFAULT_SNAPSHOT_CONFIG = {
+  analyzeForms: true,
+  detectModals: true,
+  inferPageType: true,
+  generateDescriptions: true,
+  maxElements: 500
+};
+var SemanticSnapshotManager = class {
+  constructor(config = {}) {
+    this.history = [];
+    this.maxHistorySize = 10;
+    this.snapshotCounter = 0;
+    this.config = { ...DEFAULT_SNAPSHOT_CONFIG, ...config };
+    this.searchEngine = new SearchEngine();
+  }
+  /**
+   * Create a semantic snapshot from a control snapshot
+   */
+  createSnapshot(controlSnapshot, pageContext) {
+    const snapshotId = `snapshot-${++this.snapshotCounter}-${Date.now()}`;
+    const aiElements = this.convertElements(controlSnapshot.elements);
+    this.searchEngine.updateElements(aiElements);
+    const fullPageContext = this.buildPageContext(aiElements, pageContext);
+    const forms = this.config.analyzeForms ? this.analyzeForms(aiElements) : [];
+    const modals = this.config.detectModals ? this.detectModals(aiElements) : [];
+    const elementCounts = this.countElementTypes(aiElements);
+    const summary = generatePageSummary(aiElements, fullPageContext);
+    const focusedElement = aiElements.find((el) => el.state.focused)?.id;
+    const snapshot = {
+      timestamp: Date.now(),
+      snapshotId,
+      page: fullPageContext,
+      elements: aiElements.slice(0, this.config.maxElements),
+      forms,
+      activeModals: modals,
+      focusedElement,
+      summary,
+      elementCounts
+    };
+    this.addToHistory(snapshot);
+    return snapshot;
+  }
+  /**
+   * Get the last snapshot
+   */
+  getLastSnapshot() {
+    if (this.history.length === 0) return null;
+    return this.history[this.history.length - 1].snapshot;
+  }
+  /**
+   * Get snapshot by ID
+   */
+  getSnapshot(snapshotId) {
+    const entry = this.history.find((h) => h.snapshot.snapshotId === snapshotId);
+    return entry?.snapshot || null;
+  }
+  /**
+   * Get snapshot history
+   */
+  getHistory() {
+    return this.history.map((h) => h.snapshot);
+  }
+  /**
+   * Clear history
+   */
+  clearHistory() {
+    this.history = [];
+  }
+  /**
+   * Convert control snapshot elements to AI elements
+   */
+  convertElements(elements) {
+    return elements.map((el) => this.convertElement(el));
+  }
+  /**
+   * Convert a single element to AI element
+   */
+  convertElement(element) {
+    const aliases = generateAliases({
+      textContent: element.state.textContent,
+      elementType: element.type,
+      id: element.id,
+      labelText: element.label
+    });
+    const description = this.config.generateDescriptions ? generateDescription({
+      textContent: element.state.textContent,
+      elementType: element.type,
+      id: element.id,
+      labelText: element.label
+    }) : element.label || element.id;
+    const purpose = generatePurpose({
+      textContent: element.state.textContent,
+      elementType: element.type
+    });
+    const suggestedActions = generateSuggestedActions({
+      textContent: element.state.textContent,
+      elementType: element.type
+    });
+    return {
+      id: element.id,
+      type: element.type,
+      label: element.label,
+      tagName: this.inferTagName(element.type),
+      role: this.inferRole(element.type),
+      accessibleName: element.label || element.state.textContent?.trim(),
+      actions: element.actions,
+      state: element.state,
+      registered: true,
+      description,
+      aliases,
+      purpose,
+      suggestedActions,
+      semanticType: this.inferSemanticType(element)
+    };
+  }
+  /**
+   * Build full page context
+   */
+  buildPageContext(elements, partial) {
+    const url = partial?.url || (typeof window !== "undefined" ? window.location.href : "");
+    const title = partial?.title || (typeof document !== "undefined" ? document.title : "");
+    const pageType = this.config.inferPageType ? inferPageType(url, title, elements) : partial?.pageType || "unknown";
+    const activeModals = elements.filter((el) => el.type === "dialog" && el.state.visible).map((el) => el.id);
+    return {
+      url,
+      title,
+      pageType,
+      activeModals: partial?.activeModals || activeModals,
+      focusedElement: partial?.focusedElement || elements.find((el) => el.state.focused)?.id,
+      navigation: partial?.navigation
+    };
+  }
+  /**
+   * Analyze forms in the snapshot
+   */
+  analyzeForms(elements) {
+    const forms = [];
+    const formElements = elements.filter((el) => el.type === "form");
+    if (formElements.length === 0) {
+      const implicitForm = this.detectImplicitForm(elements);
+      if (implicitForm) {
+        forms.push(implicitForm);
+      }
+    } else {
+      for (const form of formElements) {
+        const formState = this.analyzeForm(form, elements);
+        if (formState) {
+          forms.push(formState);
+        }
+      }
+    }
+    return forms;
+  }
+  /**
+   * Detect implicit form from inputs
+   */
+  detectImplicitForm(elements) {
+    const inputs = elements.filter(
+      (el) => el.type === "input" || el.type === "textarea" || el.type === "select" || el.type === "checkbox"
+    );
+    if (inputs.length === 0) return null;
+    const submitButton = elements.find(
+      (el) => el.type === "button" && el.state.visible && (el.semanticType === "submit-button" || el.state.textContent?.toLowerCase().match(/submit|save|send|continue/))
+    );
+    const fields = this.analyzeFormFields(inputs);
+    const hasErrors = fields.some((f) => !f.valid);
+    return {
+      id: "implicit-form",
+      purpose: this.inferFormPurpose(inputs),
+      fields,
+      isValid: !hasErrors,
+      submitButton: submitButton?.id,
+      isDirty: fields.some((f) => f.value !== "" && f.touched)
+    };
+  }
+  /**
+   * Analyze a specific form
+   */
+  analyzeForm(form, allElements) {
+    const inputs = allElements.filter(
+      (el) => (el.type === "input" || el.type === "textarea" || el.type === "select") && el.state.visible
+    );
+    const fields = this.analyzeFormFields(inputs);
+    const hasErrors = fields.some((f) => !f.valid);
+    const submitButton = allElements.find(
+      (el) => el.type === "button" && el.state.visible && el.semanticType === "submit-button"
+    );
+    return {
+      id: form.id,
+      name: form.label,
+      purpose: form.purpose,
+      fields,
+      isValid: !hasErrors,
+      submitButton: submitButton?.id,
+      isDirty: fields.some((f) => f.value !== "")
+    };
+  }
+  /**
+   * Analyze form fields
+   */
+  analyzeFormFields(inputs) {
+    return inputs.map((input) => ({
+      id: input.id,
+      label: input.accessibleName || input.label || input.id,
+      type: input.type,
+      value: input.state.value || "",
+      valid: true,
+      // Would need validation state
+      required: false,
+      // Would need DOM access
+      touched: input.state.focused || (input.state.value?.length || 0) > 0
+    }));
+  }
+  /**
+   * Detect modal dialogs
+   */
+  detectModals(elements) {
+    const modals = [];
+    const dialogElements = elements.filter(
+      (el) => el.type === "dialog" && el.state.visible
+    );
+    for (const dialog of dialogElements) {
+      const closeButton = elements.find(
+        (el) => el.type === "button" && el.state.visible && (el.semanticType === "cancel-button" || el.state.textContent?.toLowerCase().match(/close|cancel|x|dismiss/))
+      );
+      const primaryAction = elements.find(
+        (el) => el.type === "button" && el.state.visible && el.semanticType === "submit-button"
+      );
+      modals.push({
+        id: dialog.id,
+        title: dialog.accessibleName || dialog.label,
+        type: this.inferModalType(dialog),
+        blocking: true,
+        // Assume dialogs are blocking
+        closeButton: closeButton?.id,
+        primaryAction: primaryAction?.id
+      });
+    }
+    return modals;
+  }
+  /**
+   * Infer modal type
+   */
+  inferModalType(dialog) {
+    const text = (dialog.accessibleName || dialog.state.textContent || "").toLowerCase();
+    if (text.includes("alert") || text.includes("warning") || text.includes("error")) {
+      return "alert";
+    }
+    if (text.includes("confirm") || text.includes("are you sure")) {
+      return "confirm";
+    }
+    if (text.includes("prompt") || text.includes("enter")) {
+      return "prompt";
+    }
+    return "dialog";
+  }
+  /**
+   * Count elements by type
+   */
+  countElementTypes(elements) {
+    const counts = {};
+    for (const el of elements) {
+      const type = el.type.toLowerCase();
+      counts[type] = (counts[type] || 0) + 1;
+    }
+    return counts;
+  }
+  /**
+   * Infer form purpose from fields
+   */
+  inferFormPurpose(fields) {
+    const labels = fields.map(
+      (f) => (f.accessibleName || f.label || "").toLowerCase()
+    );
+    const allLabels = labels.join(" ");
+    if (allLabels.includes("email") && allLabels.includes("password")) {
+      if (allLabels.includes("confirm") || allLabels.includes("name")) {
+        return "Registration";
+      }
+      return "Login";
+    }
+    if (allLabels.includes("search")) return "Search";
+    if (allLabels.includes("address") || allLabels.includes("city")) return "Address";
+    if (allLabels.includes("card") || allLabels.includes("payment")) return "Payment";
+    if (allLabels.includes("contact") || allLabels.includes("message")) return "Contact";
+    return "Form";
+  }
+  /**
+   * Infer tag name from element type
+   */
+  inferTagName(type) {
+    const typeMap = {
+      button: "button",
+      input: "input",
+      textarea: "textarea",
+      select: "select",
+      checkbox: "input",
+      radio: "input",
+      link: "a",
+      form: "form",
+      dialog: "dialog"
+    };
+    return typeMap[type] || "div";
+  }
+  /**
+   * Infer ARIA role from element type
+   */
+  inferRole(type) {
+    const roleMap = {
+      button: "button",
+      input: "textbox",
+      textarea: "textbox",
+      select: "combobox",
+      checkbox: "checkbox",
+      radio: "radio",
+      link: "link",
+      dialog: "dialog",
+      menu: "menu",
+      menuitem: "menuitem",
+      tab: "tab"
+    };
+    return roleMap[type];
+  }
+  /**
+   * Infer semantic type
+   */
+  inferSemanticType(element) {
+    const text = (element.state.textContent || element.label || "").toLowerCase();
+    const type = element.type.toLowerCase();
+    if (type === "button") {
+      if (text.match(/submit|save|confirm|ok|done|apply/)) return "submit-button";
+      if (text.match(/cancel|close|dismiss/)) return "cancel-button";
+      if (text.match(/delete|remove|trash/)) return "delete-button";
+      if (text.match(/add|create|new|\+/)) return "add-button";
+      if (text.match(/edit|modify/)) return "edit-button";
+      if (text.match(/next|continue/)) return "next-button";
+      if (text.match(/back|previous/)) return "back-button";
+      return "action-button";
+    }
+    if (type === "input") {
+      if (text.includes("email") || element.id.includes("email")) return "email-input";
+      if (text.includes("password") || element.id.includes("password")) return "password-input";
+      if (text.includes("search") || element.id.includes("search")) return "search-input";
+      return "text-input";
+    }
+    return type;
+  }
+  /**
+   * Add snapshot to history
+   */
+  addToHistory(snapshot) {
+    this.history.push({
+      snapshot,
+      timestamp: Date.now()
+    });
+    if (this.history.length > this.maxHistorySize) {
+      this.history = this.history.slice(-this.maxHistorySize);
+    }
+  }
+};
+
+// src/ai/semantic-diff.ts
+var DEFAULT_DIFF_CONFIG = {
+  ignoreInsignificant: true,
+  trackedProperties: ["visible", "enabled", "focused", "checked", "value", "textContent"],
+  generateSuggestions: true,
+  maxModifications: 20
+};
+var INSIGNIFICANT_PROPERTIES = /* @__PURE__ */ new Set(["rect", "computedStyles", "innerHTML"]);
+function computeDiff(fromSnapshot, toSnapshot, config = {}) {
+  const startTime = performance.now();
+  const finalConfig = { ...DEFAULT_DIFF_CONFIG, ...config };
+  const fromElements = new Map(fromSnapshot.elements.map((el) => [el.id, el]));
+  const toElements = new Map(toSnapshot.elements.map((el) => [el.id, el]));
+  const appeared = [];
+  for (const [id, element] of toElements) {
+    if (!fromElements.has(id)) {
+      appeared.push({
+        elementId: id,
+        description: element.description,
+        type: element.type,
+        semanticType: element.semanticType
+      });
+    }
+  }
+  const disappeared = [];
+  for (const [id, element] of fromElements) {
+    if (!toElements.has(id)) {
+      disappeared.push({
+        elementId: id,
+        description: element.description,
+        type: element.type,
+        semanticType: element.semanticType
+      });
+    }
+  }
+  const modified = [];
+  for (const [id, toElement] of toElements) {
+    const fromElement = fromElements.get(id);
+    if (fromElement) {
+      const modifications = compareElements(fromElement, toElement, finalConfig);
+      modified.push(...modifications);
+    }
+  }
+  const limitedModifications = modified.slice(0, finalConfig.maxModifications);
+  const probableTrigger = detectTrigger(appeared, disappeared, limitedModifications);
+  const suggestedActions = finalConfig.generateSuggestions ? generateSuggestedActionsFromDiff(appeared, disappeared, limitedModifications, probableTrigger) : void 0;
+  const pageChanges = detectPageChanges(fromSnapshot, toSnapshot);
+  const summary = generateDiffSummary(
+    appeared.map((e) => e.description),
+    disappeared.map((e) => e.description),
+    limitedModifications
+  );
+  return {
+    summary,
+    fromSnapshotId: fromSnapshot.snapshotId,
+    toSnapshotId: toSnapshot.snapshotId,
+    changes: {
+      appeared,
+      disappeared,
+      modified: limitedModifications
+    },
+    probableTrigger,
+    suggestedActions,
+    pageChanges,
+    durationMs: performance.now() - startTime,
+    timestamp: Date.now()
+  };
+}
+function compareElements(fromElement, toElement, config) {
+  const modifications = [];
+  for (const property of config.trackedProperties) {
+    const fromValue = getPropertyValue(fromElement, property);
+    const toValue = getPropertyValue(toElement, property);
+    if (fromValue !== toValue) {
+      const isSignificant = isSignificantChange(property, fromValue, toValue);
+      if (!config.ignoreInsignificant || isSignificant) {
+        modifications.push({
+          elementId: toElement.id,
+          description: toElement.description,
+          property,
+          from: formatValue(fromValue),
+          to: formatValue(toValue),
+          significant: isSignificant
+        });
+      }
+    }
+  }
+  return modifications;
+}
+function getPropertyValue(element, property) {
+  if (property in element.state) {
+    return element.state[property];
+  }
+  return element[property];
+}
+function isSignificantChange(property, fromValue, toValue) {
+  if (INSIGNIFICANT_PROPERTIES.has(property)) {
+    return false;
+  }
+  if (property === "visible") {
+    return true;
+  }
+  if (property === "enabled") {
+    return true;
+  }
+  if (property === "focused") {
+    return true;
+  }
+  if (property === "checked") {
+    return true;
+  }
+  if (property === "value") {
+    return Boolean(fromValue) || Boolean(toValue);
+  }
+  if (property === "textContent") {
+    const fromText = String(fromValue || "");
+    const toText = String(toValue || "");
+    return fromText.trim() !== toText.trim();
+  }
+  return true;
+}
+function formatValue(value) {
+  if (value === void 0) return "undefined";
+  if (value === null) return "null";
+  if (typeof value === "boolean") return value ? "true" : "false";
+  if (typeof value === "string") {
+    if (value.length > 50) {
+      return value.substring(0, 47) + "...";
+    }
+    return value;
+  }
+  if (typeof value === "object") {
+    return JSON.stringify(value);
+  }
+  return String(value);
+}
+function detectTrigger(appeared, disappeared, modified) {
+  const hasNewErrors = appeared.some(
+    (e) => e.description.toLowerCase().includes("error") || e.type === "error"
+  );
+  if (hasNewErrors) {
+    return "Form validation";
+  }
+  const hasNewModal = appeared.some(
+    (e) => e.type === "dialog" || e.semanticType?.includes("dialog")
+  );
+  if (hasNewModal) {
+    return "Modal opened";
+  }
+  const hasModalDismissed = disappeared.some(
+    (e) => e.type === "dialog" || e.semanticType?.includes("dialog")
+  );
+  if (hasModalDismissed) {
+    return "Modal closed";
+  }
+  const hasLoading = modified.some((m) => m.description.toLowerCase().includes("loading"));
+  if (hasLoading) {
+    return "Loading state change";
+  }
+  const hasFocusChange = modified.some((m) => m.property === "focused");
+  if (hasFocusChange && modified.length <= 2) {
+    return "Focus changed";
+  }
+  const hasValueChange = modified.some((m) => m.property === "value");
+  if (hasValueChange && modified.length <= 2) {
+    return "User input";
+  }
+  const visibilityChanges = modified.filter((m) => m.property === "visible");
+  if (visibilityChanges.length > 0 && visibilityChanges.length <= 5) {
+    return "UI expansion/collapse";
+  }
+  if (appeared.length > 5) {
+    return "Page navigation";
+  }
+  return void 0;
+}
+function detectPageChanges(fromSnapshot, toSnapshot) {
+  const urlChanged = fromSnapshot.page.url !== toSnapshot.page.url;
+  const titleChanged = fromSnapshot.page.title !== toSnapshot.page.title;
+  if (!urlChanged && !titleChanged) {
+    return void 0;
+  }
+  return {
+    urlChanged,
+    titleChanged,
+    newUrl: urlChanged ? toSnapshot.page.url : void 0,
+    newTitle: titleChanged ? toSnapshot.page.title : void 0
+  };
+}
+function generateSuggestedActionsFromDiff(appeared, disappeared, modified, trigger) {
+  const suggestions = [];
+  if (trigger === "Form validation") {
+    suggestions.push("Fix the validation errors before submitting");
+  }
+  if (trigger === "Modal opened") {
+    const modal = appeared.find(
+      (e) => e.type === "dialog" || e.semanticType?.includes("dialog")
+    );
+    if (modal) {
+      suggestions.push(`Interact with the "${modal.description}" dialog`);
+    }
+  }
+  if (trigger === "Modal closed") {
+    suggestions.push("Continue with the main page interaction");
+  }
+  for (const element of appeared.slice(0, 3)) {
+    if (element.type === "button" && element.semanticType === "submit-button") {
+      suggestions.push(`Click the "${element.description}" to proceed`);
+    }
+    if (element.description.toLowerCase().includes("error")) {
+      suggestions.push(`Address the error: ${element.description}`);
+    }
+  }
+  for (const mod of modified.slice(0, 3)) {
+    if (mod.property === "enabled" && mod.to === "true") {
+      suggestions.push(`"${mod.description}" is now enabled`);
+    }
+    if (mod.property === "visible" && mod.to === "true") {
+      suggestions.push(`"${mod.description}" is now visible`);
+    }
+  }
+  return suggestions.slice(0, 5);
+}
+var SemanticDiffManager = class {
+  constructor(config = {}) {
+    this.lastSnapshot = null;
+    this.config = { ...DEFAULT_DIFF_CONFIG, ...config };
+  }
+  /**
+   * Update with new snapshot and get diff
+   */
+  update(newSnapshot) {
+    if (!this.lastSnapshot) {
+      this.lastSnapshot = newSnapshot;
+      return null;
+    }
+    const diff = computeDiff(this.lastSnapshot, newSnapshot, this.config);
+    this.lastSnapshot = newSnapshot;
+    return diff;
+  }
+  /**
+   * Get diff from a specific snapshot to current
+   */
+  diffFrom(fromSnapshot) {
+    if (!this.lastSnapshot) return null;
+    return computeDiff(fromSnapshot, this.lastSnapshot, this.config);
+  }
+  /**
+   * Reset the manager
+   */
+  reset() {
+    this.lastSnapshot = null;
+  }
+  /**
+   * Get the last known snapshot
+   */
+  getLastSnapshot() {
+    return this.lastSnapshot;
+  }
+};
+
+// src/server/handlers.ts
+function success(data) {
+  return {
+    success: true,
+    data,
+    timestamp: Date.now()
+  };
+}
+function error(message, code) {
+  return {
+    success: false,
+    error: message,
+    code,
+    timestamp: Date.now()
+  };
+}
+function getRecoverySuggestions(errorCode) {
+  switch (errorCode) {
+    case "ELEMENT_NOT_FOUND":
+      return [
+        { suggestion: "Wait for the page to fully load", command: "wait for page to load", confidence: 0.7, retryable: true },
+        { suggestion: "Use a different description for the element", confidence: 0.8, retryable: false },
+        { suggestion: "Scroll the page to reveal the element", command: "scroll down", confidence: 0.6, retryable: true }
+      ];
+    case "ELEMENT_NOT_VISIBLE":
+      return [
+        { suggestion: "Scroll to make the element visible", command: "scroll to element", confidence: 0.9, retryable: true },
+        { suggestion: "Wait for any loading overlays to disappear", confidence: 0.7, retryable: true },
+        { suggestion: "Close any blocking modals or popups", command: "click close button", confidence: 0.8, retryable: true }
+      ];
+    case "ELEMENT_NOT_ENABLED":
+      return [
+        { suggestion: "Fill in required fields first", confidence: 0.8, retryable: false },
+        { suggestion: "Complete prerequisite steps in the form", confidence: 0.7, retryable: false },
+        { suggestion: "Wait for the element to become enabled", command: "wait for element to be enabled", confidence: 0.6, retryable: true }
+      ];
+    case "ELEMENT_NOT_INTERACTABLE":
+      return [
+        { suggestion: "Close any modal or popup blocking the element", command: "click close button", confidence: 0.9, retryable: true },
+        { suggestion: "Wait for animations to complete", confidence: 0.7, retryable: true },
+        { suggestion: "Scroll the element into the viewport", command: "scroll to element", confidence: 0.8, retryable: true }
+      ];
+    case "ACTION_TIMEOUT":
+      return [
+        { suggestion: "Increase the timeout duration", confidence: 0.8, retryable: true },
+        { suggestion: "Check if the condition can ever be met", confidence: 0.7, retryable: false },
+        { suggestion: "Verify the page is responding", command: "check page status", confidence: 0.6, retryable: true }
+      ];
+    case "LOW_CONFIDENCE":
+      return [
+        { suggestion: "Use the exact text shown on the element", confidence: 0.9, retryable: false },
+        { suggestion: "Try a different description that more closely matches the element", confidence: 0.8, retryable: false },
+        { suggestion: "Lower the confidence threshold if the match is correct", confidence: 0.7, retryable: true }
+      ];
+    case "AMBIGUOUS_MATCH":
+      return [
+        { suggestion: "Be more specific about which element you mean", confidence: 0.9, retryable: false },
+        { suggestion: "Include the section or form name in the description", confidence: 0.8, retryable: false },
+        { suggestion: "Use the element ID directly", confidence: 0.7, retryable: false }
+      ];
+    default:
+      return [
+        { suggestion: "Try a different approach or check the page state", confidence: 0.5, retryable: false }
+      ];
+  }
+}
+function createFailureDetails(errorCode, message, options = {}) {
+  const retryableErrors = [
+    "ELEMENT_NOT_VISIBLE",
+    "ACTION_TIMEOUT",
+    "LOW_CONFIDENCE",
+    "NETWORK_ERROR",
+    "STATE_NOT_REACHED"
+  ];
+  return {
+    errorCode,
+    message,
+    elementId: options.elementId,
+    selectorsTried: options.selectorsTried,
+    suggestedActions: getRecoverySuggestions(errorCode),
+    retryRecommended: retryableErrors.includes(errorCode),
+    durationMs: options.durationMs,
+    timeoutMs: options.timeoutMs
+  };
+}
+function createHandlers(registry, actionExecutor, config = {}) {
+  const searchEngine = new SearchEngine();
+  const nlExecutor = new NLActionExecutor();
+  const assertionExecutor = new AssertionExecutor();
+  const snapshotManager = new SemanticSnapshotManager();
+  const diffManager = new SemanticDiffManager();
+  function refreshElements() {
+    const elements = registry.getAllElements();
+    searchEngine.updateElements(elements);
+    nlExecutor.updateElements(elements);
+    nlExecutor.setActionExecutor(actionExecutor);
+    assertionExecutor.updateElements(elements);
+  }
+  return {
+    // =========================================================================
+    // Render Log Handlers
+    // =========================================================================
+    getRenderLog: async (query) => {
+      try {
+        const entries = registry.getRenderLog?.() ?? [];
+        let filtered = entries;
+        if (query?.type) {
+          filtered = filtered.filter((e) => e.type === query.type);
+        }
+        if (query?.since) {
+          filtered = filtered.filter((e) => e.timestamp >= query.since);
+        }
+        if (query?.until) {
+          filtered = filtered.filter((e) => e.timestamp <= query.until);
+        }
+        if (query?.limit) {
+          filtered = filtered.slice(0, query.limit);
+        }
+        return success(filtered);
+      } catch (err) {
+        return error(err.message, "RENDER_LOG_ERROR");
+      }
+    },
+    clearRenderLog: async () => {
+      try {
+        registry.clearRenderLog?.();
+        return success(void 0);
+      } catch (err) {
+        return error(err.message, "RENDER_LOG_ERROR");
+      }
+    },
+    captureSnapshot: async () => {
+      try {
+        const snapshot = registry.captureSnapshot?.();
+        return success(snapshot);
+      } catch (err) {
+        return error(err.message, "SNAPSHOT_ERROR");
+      }
+    },
+    getRenderLogPath: async () => {
+      return success({ path: config.renderLogPath || "" });
+    },
+    // =========================================================================
+    // Element Handlers
+    // =========================================================================
+    getElements: async () => {
+      try {
+        const elements = registry.getAllElements();
+        return success(elements);
+      } catch (err) {
+        return error(err.message, "ELEMENTS_ERROR");
+      }
+    },
+    getElement: async (id) => {
+      try {
+        const element = registry.getElement(id);
+        if (!element) {
+          const failureDetails = createFailureDetails("ELEMENT_NOT_FOUND", `Element not found: ${id}`, {
+            elementId: id,
+            selectorsTried: [id]
+          });
+          return {
+            success: false,
+            error: `Element not found: ${id}`,
+            code: "ELEMENT_NOT_FOUND",
+            data: { failureDetails },
+            timestamp: Date.now()
+          };
+        }
+        return success(element);
+      } catch (err) {
+        return error(err.message, "ELEMENT_ERROR");
+      }
+    },
+    getElementState: async (id) => {
+      try {
+        const element = registry.getElement(id);
+        if (!element) {
+          return error(`Element not found: ${id}`, "NOT_FOUND");
+        }
+        return success(element.state);
+      } catch (err) {
+        return error(err.message, "ELEMENT_STATE_ERROR");
+      }
+    },
+    executeElementAction: async (id, request) => {
+      const startTime = Date.now();
+      try {
+        const element = registry.getElement(id);
+        if (!element) {
+          const failureDetails = createFailureDetails("ELEMENT_NOT_FOUND", `Element not found: ${id}`, {
+            elementId: id,
+            selectorsTried: [id],
+            durationMs: Date.now() - startTime
+          });
+          return {
+            success: false,
+            error: `Element not found: ${id}`,
+            code: "ELEMENT_NOT_FOUND",
+            data: {
+              success: false,
+              error: `Element not found: ${id}`,
+              failureDetails,
+              durationMs: Date.now() - startTime,
+              timestamp: Date.now()
+            },
+            timestamp: Date.now()
+          };
+        }
+        const result = await actionExecutor.executeAction(id, {
+          action: request.action,
+          params: request.params,
+          waitOptions: request.waitOptions
+        });
+        if (result && typeof result === "object" && "success" in result && !result.success) {
+          const actionResult = result;
+          let errorCode = "UNKNOWN_ERROR";
+          const errorMsg = actionResult.error?.toLowerCase() || "";
+          if (errorMsg.includes("not found")) {
+            errorCode = "ELEMENT_NOT_FOUND";
+          } else if (errorMsg.includes("not visible") || errorMsg.includes("hidden")) {
+            errorCode = "ELEMENT_NOT_VISIBLE";
+          } else if (errorMsg.includes("disabled") || errorMsg.includes("not enabled")) {
+            errorCode = "ELEMENT_NOT_ENABLED";
+          } else if (errorMsg.includes("timeout")) {
+            errorCode = "ACTION_TIMEOUT";
+          } else if (errorMsg.includes("blocked") || errorMsg.includes("interactable")) {
+            errorCode = "ELEMENT_NOT_INTERACTABLE";
+          }
+          const failureDetails = createFailureDetails(errorCode, actionResult.error || "Action failed", {
+            elementId: id,
+            durationMs: Date.now() - startTime
+          });
+          return success({
+            ...actionResult,
+            failureDetails
+          });
+        }
+        return success(result);
+      } catch (err) {
+        const errorMessage = err.message;
+        let errorCode = "UNKNOWN_ERROR";
+        if (errorMessage.includes("not found")) {
+          errorCode = "ELEMENT_NOT_FOUND";
+        } else if (errorMessage.includes("timeout")) {
+          errorCode = "ACTION_TIMEOUT";
+        } else if (errorMessage.includes("network") || errorMessage.includes("fetch")) {
+          errorCode = "NETWORK_ERROR";
+        }
+        const failureDetails = createFailureDetails(errorCode, errorMessage, {
+          elementId: id,
+          durationMs: Date.now() - startTime
+        });
+        return {
+          success: false,
+          error: errorMessage,
+          code: errorCode,
+          data: {
+            success: false,
+            error: errorMessage,
+            failureDetails,
+            durationMs: Date.now() - startTime,
+            timestamp: Date.now()
+          },
+          timestamp: Date.now()
+        };
+      }
+    },
+    // =========================================================================
+    // Component Handlers
+    // =========================================================================
+    getComponents: async () => {
+      try {
+        const components = registry.getAllComponents();
+        return success(components);
+      } catch (err) {
+        return error(err.message, "COMPONENTS_ERROR");
+      }
+    },
+    getComponent: async (id) => {
+      try {
+        const component = registry.getComponent(id);
+        if (!component) {
+          return error(`Component not found: ${id}`, "NOT_FOUND");
+        }
+        return success(component);
+      } catch (err) {
+        return error(err.message, "COMPONENT_ERROR");
+      }
+    },
+    getComponentState: async (id) => {
+      try {
+        const component = registry.getComponent(id);
+        if (!component) {
+          return error(`Component not found: ${id}`, "NOT_FOUND");
+        }
+        if (registry.getComponentState) {
+          const stateResponse = registry.getComponentState(id);
+          if (!stateResponse) {
+            return error(`Component not found or not mounted: ${id}`, "NOT_FOUND");
+          }
+          return success(stateResponse);
+        }
+        const comp = component;
+        return success({
+          state: comp.getState?.() ?? {},
+          computed: comp.getComputed?.() ?? {},
+          timestamp: Date.now()
+        });
+      } catch (err) {
+        return error(err.message, "COMPONENT_STATE_ERROR");
+      }
+    },
+    executeComponentAction: async (id, request) => {
+      try {
+        const result = await actionExecutor.executeComponentAction(id, {
+          action: request.action,
+          params: request.params
+        });
+        return success(result);
+      } catch (err) {
+        return error(err.message, "COMPONENT_ACTION_ERROR");
+      }
+    },
+    // =========================================================================
+    // Find/Discovery Handlers
+    // =========================================================================
+    find: async (request) => {
+      try {
+        const findRequest = request;
+        const elements = registry.findElements?.(findRequest) ?? registry.getAllElements();
+        return success({ elements, timestamp: Date.now(), total: elements.length, durationMs: 0 });
+      } catch (err) {
+        return error(err.message, "FIND_ERROR");
+      }
+    },
+    discover: async (request) => {
+      try {
+        const findRequest = request;
+        const elements = registry.findElements?.(findRequest) ?? registry.getAllElements();
+        return success({ elements, timestamp: Date.now(), total: elements.length, durationMs: 0 });
+      } catch (err) {
+        return error(err.message, "DISCOVER_ERROR");
+      }
+    },
+    getControlSnapshot: async () => {
+      try {
+        const snapshot = registry.createSnapshot();
+        return success(snapshot);
+      } catch (err) {
+        return error(err.message, "SNAPSHOT_ERROR");
+      }
+    },
+    // =========================================================================
+    // Workflow Handlers
+    // =========================================================================
+    getWorkflows: async () => {
+      try {
+        const workflows = registry.getAllWorkflows?.() ?? [];
+        return success(workflows);
+      } catch (err) {
+        return error(err.message, "WORKFLOWS_ERROR");
+      }
+    },
+    runWorkflow: async (id, _request) => {
+      try {
+        const workflow = registry.getWorkflow?.(id);
+        if (!workflow) {
+          return error(`Workflow not found: ${id}`, "NOT_FOUND");
+        }
+        const runId = `run-${Date.now()}`;
+        return success({
+          runId,
+          workflowId: id,
+          status: "pending",
+          startedAt: Date.now(),
+          steps: [],
+          totalSteps: 0
+        });
+      } catch (err) {
+        return error(err.message, "WORKFLOW_ERROR");
+      }
+    },
+    getWorkflowStatus: async (runId) => {
+      try {
+        return success({
+          runId,
+          workflowId: "",
+          status: "completed",
+          completedAt: Date.now(),
+          startedAt: Date.now(),
+          steps: [],
+          totalSteps: 0
+        });
+      } catch (err) {
+        return error(err.message, "WORKFLOW_STATUS_ERROR");
+      }
+    },
+    // =========================================================================
+    // Debug Handlers
+    // =========================================================================
+    getActionHistory: async (limit) => {
+      try {
+        const history = registry.getActionHistory?.() ?? [];
+        const limited = limit ? history.slice(-limit) : history;
+        return success(limited);
+      } catch (err) {
+        return error(err.message, "ACTION_HISTORY_ERROR");
+      }
+    },
+    getMetrics: async () => {
+      try {
+        const metrics = registry.getMetrics?.() ?? {
+          elementCount: registry.getAllElements().length,
+          componentCount: registry.getAllComponents().length
+        };
+        return success(metrics);
+      } catch (err) {
+        return error(err.message, "METRICS_ERROR");
+      }
+    },
+    highlightElement: async (id) => {
+      try {
+        registry.highlightElement?.(id);
+        return success(void 0);
+      } catch (err) {
+        return error(err.message, "HIGHLIGHT_ERROR");
+      }
+    },
+    getElementTree: async () => {
+      try {
+        const tree = registry.getElementTree?.() ?? { root: null, elements: [] };
+        return success(tree);
+      } catch (err) {
+        return error(err.message, "ELEMENT_TREE_ERROR");
+      }
+    },
+    // =========================================================================
+    // AI-Native Handlers
+    // =========================================================================
+    aiSearch: async (criteria) => {
+      try {
+        refreshElements();
+        const response = searchEngine.search(criteria);
+        return success(response);
+      } catch (err) {
+        return error(err.message, "AI_SEARCH_ERROR");
+      }
+    },
+    aiExecute: async (request) => {
+      try {
+        refreshElements();
+        const response = await nlExecutor.execute(request);
+        return success(response);
+      } catch (err) {
+        return error(err.message, "AI_EXECUTE_ERROR");
+      }
+    },
+    aiAssert: async (request) => {
+      try {
+        refreshElements();
+        const result = await assertionExecutor.assert(request);
+        return success(result);
+      } catch (err) {
+        return error(err.message, "AI_ASSERT_ERROR");
+      }
+    },
+    aiAssertBatch: async (request) => {
+      try {
+        refreshElements();
+        const result = await assertionExecutor.assertBatch(request);
+        return success(result);
+      } catch (err) {
+        return error(err.message, "AI_ASSERT_BATCH_ERROR");
+      }
+    },
+    getSemanticSnapshot: async () => {
+      try {
+        const controlSnapshot = registry.createSnapshot();
+        const snapshot = snapshotManager.createSnapshot(controlSnapshot);
+        return success(snapshot);
+      } catch (err) {
+        return error(err.message, "SEMANTIC_SNAPSHOT_ERROR");
+      }
+    },
+    getSemanticDiff: async (_since) => {
+      try {
+        const controlSnapshot = registry.createSnapshot();
+        const currentSnapshot = snapshotManager.createSnapshot(controlSnapshot);
+        const diff = diffManager.update(currentSnapshot);
+        return success(diff);
+      } catch (err) {
+        return error(err.message, "SEMANTIC_DIFF_ERROR");
+      }
+    },
+    getPageSummary: async () => {
+      try {
+        const snapshot = registry.createSnapshot();
+        const elements = snapshot.elements.map((el) => ({
+          ...el,
+          description: el.label || el.id,
+          aliases: [],
+          suggestedActions: [],
+          tagName: el.type,
+          accessibleName: el.label,
+          registered: true
+        }));
+        const summary = generatePageSummary(elements);
+        return success(summary);
+      } catch (err) {
+        return error(err.message, "PAGE_SUMMARY_ERROR");
+      }
+    },
+    // =========================================================================
+    // Semantic Search Handler (Embedding-based)
+    // =========================================================================
+    aiSemanticSearch: async (criteria) => {
+      const startTime = performance.now();
+      try {
+        refreshElements();
+        const allElements = registry.getAllElements();
+        const aiElements = allElements.map((el) => {
+          const textParts = [];
+          const state = "getState" in el ? el.getState() : el.state;
+          const textContent = state?.textContent || "";
+          const label = el.label || "";
+          const accessibleName = el.accessibleName || "";
+          const placeholder = el.placeholder || "";
+          const title = el.title || "";
+          if (label) textParts.push(label);
+          if (accessibleName && accessibleName !== label) textParts.push(accessibleName);
+          if (textContent && textContent !== label && textContent !== accessibleName) {
+            textParts.push(textContent);
+          }
+          if (placeholder) textParts.push(`placeholder: ${placeholder}`);
+          if (title) textParts.push(title);
+          const combinedText = textParts.join(" ").trim() || el.id;
+          return {
+            element: {
+              id: el.id,
+              type: el.type,
+              label: el.label,
+              tagName: el.tagName || el.type,
+              role: el.role,
+              accessibleName: el.accessibleName,
+              actions: el.actions || [],
+              state: state || {},
+              registered: true,
+              description: label || el.id,
+              aliases: [],
+              suggestedActions: []
+            },
+            text: combinedText
+          };
+        });
+        let filteredElements = aiElements;
+        if (criteria.type) {
+          filteredElements = filteredElements.filter(
+            ({ element }) => element.type.toLowerCase() === criteria.type.toLowerCase()
+          );
+        }
+        if (criteria.role) {
+          filteredElements = filteredElements.filter(
+            ({ element }) => element.role?.toLowerCase() === criteria.role.toLowerCase()
+          );
+        }
+        const query = criteria.query.toLowerCase();
+        const threshold = criteria.threshold ?? 0.5;
+        const limit = criteria.limit ?? 10;
+        const scoredResults = filteredElements.map(({ element, text }) => {
+          const textLower = text.toLowerCase();
+          let similarity = 0;
+          if (textLower.includes(query)) {
+            similarity = 0.9;
+          } else {
+            const queryWords = new Set(query.split(/\s+/).filter((w) => w.length > 2));
+            const textWords = new Set(textLower.split(/\s+/).filter((w) => w.length > 2));
+            if (queryWords.size > 0 && textWords.size > 0) {
+              let matchCount = 0;
+              for (const word of queryWords) {
+                for (const textWord of textWords) {
+                  if (textWord.includes(word) || word.includes(textWord)) {
+                    matchCount++;
+                    break;
+                  }
+                }
+              }
+              similarity = matchCount / queryWords.size * 0.7;
+            }
+          }
+          return {
+            element,
+            similarity,
+            rank: 0,
+            // Will be set after sorting
+            embeddedText: text
+          };
+        });
+        const filteredResults = scoredResults.filter((r) => r.similarity >= threshold).sort((a, b) => b.similarity - a.similarity).slice(0, limit);
+        filteredResults.forEach((result, index) => {
+          result.rank = index + 1;
+        });
+        const response = {
+          results: filteredResults,
+          bestMatch: filteredResults.length > 0 ? filteredResults[0] : null,
+          scannedCount: filteredElements.length,
+          durationMs: performance.now() - startTime,
+          query: criteria.query,
+          providerInfo: {
+            provider: "text-fallback",
+            model: "simple-similarity",
+            dimension: 0
+          },
+          timestamp: Date.now()
+        };
+        return success(response);
+      } catch (err) {
+        return error(err.message, "AI_SEMANTIC_SEARCH_ERROR");
+      }
+    }
+  };
+}
+function createAIHandlers(registry, actionExecutor) {
+  const searchEngine = new SearchEngine();
+  const nlExecutor = new NLActionExecutor();
+  const assertionExecutor = new AssertionExecutor();
+  const snapshotManager = new SemanticSnapshotManager();
+  const diffManager = new SemanticDiffManager();
+  function refreshElements() {
+    const elements = registry.getAllElements();
+    searchEngine.updateElements(elements);
+    nlExecutor.updateElements(elements);
+    nlExecutor.setActionExecutor(actionExecutor);
+    assertionExecutor.updateElements(elements);
+  }
+  return {
+    aiSearch: async (criteria) => {
+      try {
+        refreshElements();
+        const response = searchEngine.search(criteria);
+        return { success: true, data: response, timestamp: Date.now() };
+      } catch (err) {
+        return { success: false, error: err.message, code: "AI_SEARCH_ERROR", timestamp: Date.now() };
+      }
+    },
+    aiExecute: async (request) => {
+      try {
+        refreshElements();
+        const response = await nlExecutor.execute(request);
+        return { success: true, data: response, timestamp: Date.now() };
+      } catch (err) {
+        return { success: false, error: err.message, code: "AI_EXECUTE_ERROR", timestamp: Date.now() };
+      }
+    },
+    aiAssert: async (request) => {
+      try {
+        refreshElements();
+        const result = await assertionExecutor.assert(request);
+        return { success: true, data: result, timestamp: Date.now() };
+      } catch (err) {
+        return { success: false, error: err.message, code: "AI_ASSERT_ERROR", timestamp: Date.now() };
+      }
+    },
+    aiAssertBatch: async (request) => {
+      try {
+        refreshElements();
+        const result = await assertionExecutor.assertBatch(request);
+        return { success: true, data: result, timestamp: Date.now() };
+      } catch (err) {
+        return { success: false, error: err.message, code: "AI_ASSERT_BATCH_ERROR", timestamp: Date.now() };
+      }
+    },
+    getSemanticSnapshot: async () => {
+      try {
+        const controlSnapshot = registry.createSnapshot();
+        const snapshot = snapshotManager.createSnapshot(controlSnapshot);
+        return { success: true, data: snapshot, timestamp: Date.now() };
+      } catch (err) {
+        return { success: false, error: err.message, code: "SEMANTIC_SNAPSHOT_ERROR", timestamp: Date.now() };
+      }
+    },
+    getSemanticDiff: async (_since) => {
+      try {
+        const controlSnapshot = registry.createSnapshot();
+        const currentSnapshot = snapshotManager.createSnapshot(controlSnapshot);
+        const diff = diffManager.update(currentSnapshot);
+        return { success: true, data: diff, timestamp: Date.now() };
+      } catch (err) {
+        return { success: false, error: err.message, code: "SEMANTIC_DIFF_ERROR", timestamp: Date.now() };
+      }
+    },
+    getPageSummary: async () => {
+      try {
+        const snapshot = registry.createSnapshot();
+        const elements = snapshot.elements.map((el) => ({
+          ...el,
+          description: el.label || el.id,
+          aliases: [],
+          suggestedActions: [],
+          tagName: el.type,
+          accessibleName: el.label,
+          registered: true
+        }));
+        const summary = generatePageSummary(elements);
+        return { success: true, data: summary, timestamp: Date.now() };
+      } catch (err) {
+        return { success: false, error: err.message, code: "PAGE_SUMMARY_ERROR", timestamp: Date.now() };
+      }
+    }
+  };
+}
+
+exports.createAIHandlers = createAIHandlers;
+exports.createHandlers = createHandlers;
+//# sourceMappingURL=handlers.js.map
+//# sourceMappingURL=handlers.js.map