@qontinui/ui-bridge 0.2.0 → 0.3.1

package/dist/specs/index.js

@@ -0,0 +1,2809 @@
+'use strict';
+
+// src/specs/types.ts
+var SPEC_CONFIG_VERSION = "1.0.0";
+var SPEC_FILE_EXTENSION = ".spec.uibridge.json";
+var VALID_ASSERTION_TYPES = [
+  "visible",
+  "hidden",
+  "enabled",
+  "disabled",
+  "focused",
+  "checked",
+  "unchecked",
+  "hasText",
+  "containsText",
+  "hasValue",
+  "hasClass",
+  "exists",
+  "notExists",
+  "count",
+  "attribute",
+  "cssProperty"
+];
+var VALID_SPEC_CATEGORIES = [
+  "element-presence",
+  "accessibility",
+  "form-validation",
+  "state-consistency",
+  "modal-dialog",
+  "navigation",
+  "cross-page-consistency",
+  "custom"
+];
+var VALID_SPEC_SEVERITIES = [
+  "critical",
+  "warning",
+  "info"
+];
+var VALID_SPEC_SOURCES = [
+  "auto",
+  "manual",
+  "ai-generated"
+];
+
+// src/specs/validator.ts
+function isValidAssertionType(value) {
+  return typeof value === "string" && VALID_ASSERTION_TYPES.includes(value);
+}
+function isValidSpecCategory(value) {
+  return typeof value === "string" && VALID_SPEC_CATEGORIES.includes(value);
+}
+function isValidSpecSeverity(value) {
+  return typeof value === "string" && VALID_SPEC_SEVERITIES.includes(value);
+}
+function isValidSpecSource(value) {
+  return typeof value === "string" && VALID_SPEC_SOURCES.includes(value);
+}
+function validateSpecAssertion(data, path = "assertion") {
+  const errors = [];
+  if (!data || typeof data !== "object") {
+    errors.push({ path, message: "must be an object" });
+    return errors;
+  }
+  const obj = data;
+  if (typeof obj.id !== "string" || obj.id.length === 0) {
+    errors.push({ path: `${path}.id`, message: "must be a non-empty string" });
+  }
+  if (typeof obj.description !== "string") {
+    errors.push({ path: `${path}.description`, message: "must be a string" });
+  }
+  if (!isValidSpecCategory(obj.category)) {
+    errors.push({
+      path: `${path}.category`,
+      message: `must be one of: ${VALID_SPEC_CATEGORIES.join(", ")}`
+    });
+  }
+  if (!isValidSpecSeverity(obj.severity)) {
+    errors.push({
+      path: `${path}.severity`,
+      message: `must be one of: ${VALID_SPEC_SEVERITIES.join(", ")}`
+    });
+  }
+  if (!obj.target || typeof obj.target !== "object") {
+    errors.push({ path: `${path}.target`, message: "must be an object" });
+  } else {
+    const target = obj.target;
+    if (target.type === "elementId") {
+      if (typeof target.elementId !== "string" || target.elementId.length === 0) {
+        errors.push({ path: `${path}.target.elementId`, message: "must be a non-empty string" });
+      }
+    } else if (target.type === "search") {
+      if (!target.criteria || typeof target.criteria !== "object") {
+        errors.push({ path: `${path}.target.criteria`, message: "must be an object" });
+      }
+    } else {
+      errors.push({ path: `${path}.target.type`, message: 'must be "elementId" or "search"' });
+    }
+  }
+  if (!isValidAssertionType(obj.assertionType)) {
+    errors.push({
+      path: `${path}.assertionType`,
+      message: `must be one of: ${VALID_ASSERTION_TYPES.join(", ")}`
+    });
+  }
+  if (!isValidSpecSource(obj.source)) {
+    errors.push({
+      path: `${path}.source`,
+      message: `must be one of: ${VALID_SPEC_SOURCES.join(", ")}`
+    });
+  }
+  if (typeof obj.reviewed !== "boolean") {
+    errors.push({ path: `${path}.reviewed`, message: "must be a boolean" });
+  }
+  if (typeof obj.enabled !== "boolean") {
+    errors.push({ path: `${path}.enabled`, message: "must be a boolean" });
+  }
+  if (obj.timeout !== void 0 && (typeof obj.timeout !== "number" || obj.timeout < 0)) {
+    errors.push({ path: `${path}.timeout`, message: "must be a non-negative number" });
+  }
+  return errors;
+}
+function validateSpecGroup(data, path = "group") {
+  const errors = [];
+  if (!data || typeof data !== "object") {
+    errors.push({ path, message: "must be an object" });
+    return errors;
+  }
+  const obj = data;
+  if (typeof obj.id !== "string" || obj.id.length === 0) {
+    errors.push({ path: `${path}.id`, message: "must be a non-empty string" });
+  }
+  if (typeof obj.name !== "string") {
+    errors.push({ path: `${path}.name`, message: "must be a string" });
+  }
+  if (typeof obj.description !== "string") {
+    errors.push({ path: `${path}.description`, message: "must be a string" });
+  }
+  if (!isValidSpecCategory(obj.category)) {
+    errors.push({
+      path: `${path}.category`,
+      message: `must be one of: ${VALID_SPEC_CATEGORIES.join(", ")}`
+    });
+  }
+  if (!isValidSpecSource(obj.source)) {
+    errors.push({
+      path: `${path}.source`,
+      message: `must be one of: ${VALID_SPEC_SOURCES.join(", ")}`
+    });
+  }
+  if (!Array.isArray(obj.assertions)) {
+    errors.push({ path: `${path}.assertions`, message: "must be an array" });
+  } else {
+    for (let i = 0; i < obj.assertions.length; i++) {
+      errors.push(...validateSpecAssertion(obj.assertions[i], `${path}.assertions[${i}]`));
+    }
+  }
+  return errors;
+}
+function validateSpecConfig(data) {
+  const errors = [];
+  if (!data || typeof data !== "object") {
+    return { valid: false, errors: [{ path: "", message: "must be an object" }] };
+  }
+  const obj = data;
+  if (obj.version !== SPEC_CONFIG_VERSION) {
+    errors.push({ path: "version", message: `must be "${SPEC_CONFIG_VERSION}"` });
+  }
+  if (obj.description !== void 0 && typeof obj.description !== "string") {
+    errors.push({ path: "description", message: "must be a string if provided" });
+  }
+  if (!Array.isArray(obj.groups)) {
+    errors.push({ path: "groups", message: "must be an array" });
+  } else {
+    for (let i = 0; i < obj.groups.length; i++) {
+      errors.push(...validateSpecGroup(obj.groups[i], `groups[${i}]`));
+    }
+  }
+  if (obj.assertions !== void 0) {
+    if (!Array.isArray(obj.assertions)) {
+      errors.push({ path: "assertions", message: "must be an array if provided" });
+    } else {
+      for (let i = 0; i < obj.assertions.length; i++) {
+        errors.push(...validateSpecAssertion(obj.assertions[i], `assertions[${i}]`));
+      }
+    }
+  }
+  if (obj.metadata !== void 0 && (typeof obj.metadata !== "object" || obj.metadata === null)) {
+    errors.push({ path: "metadata", message: "must be an object if provided" });
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+// src/specs/migration.ts
+function coerceAssertionType(raw) {
+  if (VALID_ASSERTION_TYPES.includes(raw)) {
+    return raw;
+  }
+  return null;
+}
+function coerceCategory(raw) {
+  const valid = [
+    "element-presence",
+    "accessibility",
+    "form-validation",
+    "state-consistency",
+    "modal-dialog",
+    "navigation",
+    "cross-page-consistency",
+    "custom"
+  ];
+  return valid.includes(raw) ? raw : "custom";
+}
+function coerceSeverity(raw) {
+  const valid = ["critical", "warning", "info"];
+  return valid.includes(raw) ? raw : "info";
+}
+function coerceSource(raw) {
+  if (raw === "auto" || raw === "manual" || raw === "ai-generated") return raw;
+  return "auto";
+}
+function migrateLegacyTarget(legacy) {
+  switch (legacy.type) {
+    case "elementId":
+      return {
+        type: "elementId",
+        elementId: legacy.elementId || "",
+        label: legacy.label
+      };
+    case "formId":
+      return {
+        type: "search",
+        criteria: {
+          idPattern: legacy.formId || "",
+          role: "form"
+        },
+        label: legacy.label
+      };
+    case "modalId":
+      return {
+        type: "search",
+        criteria: {
+          idPattern: legacy.modalId || "",
+          role: "dialog"
+        },
+        label: legacy.label
+      };
+    default:
+      return {
+        type: "elementId",
+        elementId: "",
+        label: legacy.label
+      };
+  }
+}
+function migrateLegacyAssertion(legacy) {
+  const assertionType = coerceAssertionType(legacy.assertionType);
+  return {
+    id: legacy.id,
+    description: legacy.description,
+    category: coerceCategory(legacy.category),
+    severity: coerceSeverity(legacy.severity),
+    target: migrateLegacyTarget(legacy.target),
+    assertionType: assertionType ?? "exists",
+    expected: legacy.expected,
+    attributeName: legacy.attributeName,
+    source: coerceSource(legacy.source),
+    reviewed: legacy.reviewed,
+    enabled: legacy.enabled,
+    notes: legacy.notes
+  };
+}
+function migrateFromTestGeneratorOutput(legacy) {
+  const groups = legacy.testSpecifications.map((spec) => ({
+    id: spec.id,
+    name: spec.name,
+    description: spec.description,
+    category: coerceCategory(spec.category),
+    assertions: spec.assertions.map(migrateLegacyAssertion),
+    stateId: spec.stateId,
+    transitionId: spec.transitionId,
+    source: coerceSource(spec.source)
+  }));
+  return {
+    version: "1.0.0",
+    description: legacy.generatorType ? `Migrated from ${legacy.generatorType} test generator output` : "Migrated from legacy test generator output",
+    groups,
+    metadata: {
+      createdAt: legacy.createdAt,
+      updatedAt: legacy.updatedAt,
+      ...legacy.snapshotMetadata?.pageUrl ? { pageUrl: legacy.snapshotMetadata.pageUrl } : {},
+      ...legacy.explorationMetadata?.targetUrl ? { pageUrl: legacy.explorationMetadata.targetUrl } : {}
+    }
+  };
+}
+
+// src/specs/store.ts
+var SpecStore = class {
+  constructor() {
+    this.configs = /* @__PURE__ */ new Map();
+    this.listeners = /* @__PURE__ */ new Set();
+  }
+  // ---------------------------------------------------------------------------
+  // CRUD — Config Level
+  // ---------------------------------------------------------------------------
+  load(specId, config) {
+    this.configs.set(specId, config);
+    this.emit({ type: "spec:loaded", specId, timestamp: Date.now() });
+  }
+  unload(specId) {
+    const existed = this.configs.delete(specId);
+    if (existed) {
+      this.emit({ type: "spec:unloaded", specId, timestamp: Date.now() });
+    }
+    return existed;
+  }
+  get(specId) {
+    return this.configs.get(specId);
+  }
+  has(specId) {
+    return this.configs.has(specId);
+  }
+  getIds() {
+    return Array.from(this.configs.keys());
+  }
+  getAll() {
+    return new Map(this.configs);
+  }
+  get count() {
+    return this.configs.size;
+  }
+  clear() {
+    this.configs.clear();
+    this.emit({ type: "spec:cleared", timestamp: Date.now() });
+  }
+  // ---------------------------------------------------------------------------
+  // CRUD — Group Level
+  // ---------------------------------------------------------------------------
+  addGroup(specId, group) {
+    const config = this.configs.get(specId);
+    if (!config) return false;
+    config.groups.push(group);
+    this.emit({ type: "spec:group-added", specId, groupId: group.id, timestamp: Date.now() });
+    return true;
+  }
+  removeGroup(specId, groupId) {
+    const config = this.configs.get(specId);
+    if (!config) return false;
+    const idx = config.groups.findIndex((g) => g.id === groupId);
+    if (idx === -1) return false;
+    config.groups.splice(idx, 1);
+    this.emit({ type: "spec:group-removed", specId, groupId, timestamp: Date.now() });
+    return true;
+  }
+  getGroup(specId, groupId) {
+    const config = this.configs.get(specId);
+    if (!config) return void 0;
+    return config.groups.find((g) => g.id === groupId);
+  }
+  // ---------------------------------------------------------------------------
+  // CRUD — Assertion Level
+  // ---------------------------------------------------------------------------
+  addAssertion(specId, groupId, assertion) {
+    const config = this.configs.get(specId);
+    if (!config) return false;
+    if (groupId) {
+      const group = config.groups.find((g) => g.id === groupId);
+      if (!group) return false;
+      group.assertions.push(assertion);
+    } else {
+      if (!config.assertions) config.assertions = [];
+      config.assertions.push(assertion);
+    }
+    this.emit({
+      type: "spec:assertion-added",
+      specId,
+      groupId: groupId ?? void 0,
+      assertionId: assertion.id,
+      timestamp: Date.now()
+    });
+    return true;
+  }
+  removeAssertion(specId, groupId, assertionId) {
+    const config = this.configs.get(specId);
+    if (!config) return false;
+    let removed = false;
+    if (groupId) {
+      const group = config.groups.find((g) => g.id === groupId);
+      if (group) {
+        const idx = group.assertions.findIndex((a) => a.id === assertionId);
+        if (idx !== -1) {
+          group.assertions.splice(idx, 1);
+          removed = true;
+        }
+      }
+    } else if (config.assertions) {
+      const idx = config.assertions.findIndex((a) => a.id === assertionId);
+      if (idx !== -1) {
+        config.assertions.splice(idx, 1);
+        removed = true;
+      }
+    }
+    if (removed) {
+      this.emit({
+        type: "spec:assertion-removed",
+        specId,
+        groupId: groupId ?? void 0,
+        assertionId,
+        timestamp: Date.now()
+      });
+    }
+    return removed;
+  }
+  toggleAssertion(specId, groupId, assertionId) {
+    const assertion = this.findAssertion(specId, groupId, assertionId);
+    if (!assertion) return false;
+    assertion.enabled = !assertion.enabled;
+    this.emit({ type: "spec:updated", specId, timestamp: Date.now() });
+    return true;
+  }
+  markReviewed(specId, groupId, assertionId) {
+    const assertion = this.findAssertion(specId, groupId, assertionId);
+    if (!assertion) return false;
+    assertion.reviewed = !assertion.reviewed;
+    this.emit({ type: "spec:updated", specId, timestamp: Date.now() });
+    return true;
+  }
+  // ---------------------------------------------------------------------------
+  // Queries
+  // ---------------------------------------------------------------------------
+  getAllAssertions() {
+    const result = [];
+    for (const config of this.configs.values()) {
+      for (const group of config.groups) {
+        result.push(...group.assertions);
+      }
+      if (config.assertions) {
+        result.push(...config.assertions);
+      }
+    }
+    return result;
+  }
+  filterAssertions(opts) {
+    return this.getAllAssertions().filter((a) => {
+      if (opts.categories && !opts.categories.includes(a.category)) return false;
+      if (opts.severities && !opts.severities.includes(a.severity)) return false;
+      if (opts.enabledOnly && !a.enabled) return false;
+      if (opts.reviewedOnly && !a.reviewed) return false;
+      return true;
+    });
+  }
+  // ---------------------------------------------------------------------------
+  // Coverage
+  // ---------------------------------------------------------------------------
+  getCoverage(allElementIds) {
+    const specifiedIdSet = /* @__PURE__ */ new Set();
+    for (const assertion of this.getAllAssertions()) {
+      if (assertion.target.type === "elementId") {
+        specifiedIdSet.add(assertion.target.elementId);
+      }
+    }
+    const specifiedIds = [];
+    const unspecifiedIds = [];
+    for (const id of allElementIds) {
+      if (specifiedIdSet.has(id)) {
+        specifiedIds.push(id);
+      } else {
+        unspecifiedIds.push(id);
+      }
+    }
+    const total = allElementIds.length;
+    return {
+      totalElements: total,
+      specifiedElements: specifiedIds.length,
+      coveragePercent: total > 0 ? specifiedIds.length / total * 100 : 0,
+      specifiedIds,
+      unspecifiedIds,
+      timestamp: Date.now()
+    };
+  }
+  // ---------------------------------------------------------------------------
+  // Import / Export
+  // ---------------------------------------------------------------------------
+  importConfig(specId, config) {
+    const result = validateSpecConfig(config);
+    if (!result.valid) return false;
+    this.configs.set(specId, config);
+    this.emit({ type: "spec:loaded", specId, timestamp: Date.now() });
+    return true;
+  }
+  exportConfig(specId) {
+    const config = this.configs.get(specId);
+    if (!config) return void 0;
+    return {
+      ...config,
+      version: SPEC_CONFIG_VERSION,
+      metadata: {
+        ...config.metadata,
+        updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+      }
+    };
+  }
+  // ---------------------------------------------------------------------------
+  // Events
+  // ---------------------------------------------------------------------------
+  on(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  emit(event) {
+    for (const listener of this.listeners) {
+      try {
+        listener(event);
+      } catch {
+      }
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Private Helpers
+  // ---------------------------------------------------------------------------
+  findAssertion(specId, groupId, assertionId) {
+    const config = this.configs.get(specId);
+    if (!config) return void 0;
+    if (groupId) {
+      const group = config.groups.find((g) => g.id === groupId);
+      if (!group) return void 0;
+      return group.assertions.find((a) => a.id === assertionId);
+    }
+    return config.assertions?.find((a) => a.id === assertionId);
+  }
+};
+var globalStore = null;
+function getGlobalSpecStore() {
+  if (!globalStore) {
+    globalStore = new SpecStore();
+  }
+  return globalStore;
+}
+function resetGlobalSpecStore() {
+  globalStore = null;
+}
+
+// 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(" ");
+}
+var CONTENT_TYPES = /* @__PURE__ */ new Set([
+  "heading",
+  "paragraph",
+  "list-item",
+  "table-cell",
+  "table-header",
+  "label",
+  "caption",
+  "blockquote",
+  "code-block",
+  "badge",
+  "status-message",
+  "metric-value",
+  "description-text",
+  "nav-text",
+  "content-generic"
+]);
+function generatePurpose(input) {
+  const text = (input.textContent || input.ariaLabel || input.title || "").toLowerCase();
+  const type = input.elementType?.toLowerCase() || "";
+  const inputType = input.inputType?.toLowerCase() || "";
+  if (CONTENT_TYPES.has(type)) {
+    switch (type) {
+      case "heading":
+        return "Section heading";
+      case "paragraph":
+        return "Body text content";
+      case "list-item":
+        return "List item";
+      case "table-cell":
+        return "Table data cell";
+      case "table-header":
+        return "Table column header";
+      case "label":
+        return "Field label or definition term";
+      case "caption":
+        return "Figure or table caption";
+      case "blockquote":
+        return "Quoted content";
+      case "code-block":
+        return "Code or preformatted text";
+      case "badge":
+        return "Status badge or tag";
+      case "status-message":
+        return "Dynamic status indicator";
+      case "metric-value":
+        return "Metric or statistic value";
+      case "description-text":
+        return "Description or definition";
+      case "nav-text":
+        return "Navigation label";
+      case "content-generic":
+        return "Text content";
+      default:
+        return "Static content";
+    }
+  }
+  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 = [];
+  if (CONTENT_TYPES.has(type)) {
+    actions.push("read text content", "verify text matches expected");
+    return 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/annotations/types.ts
+var ANNOTATION_CONFIG_VERSION = "1.0.0";
+
+// src/annotations/store.ts
+var AnnotationStore = class {
+  constructor() {
+    this.store = /* @__PURE__ */ new Map();
+    this.listeners = /* @__PURE__ */ new Set();
+  }
+  /**
+   * Get an annotation by element ID.
+   */
+  get(elementId) {
+    return this.store.get(elementId);
+  }
+  /**
+   * Get all annotations as a record.
+   */
+  getAll() {
+    const result = {};
+    for (const [id, annotation] of this.store) {
+      result[id] = annotation;
+    }
+    return result;
+  }
+  /**
+   * Set an annotation for an element. Auto-sets `updatedAt`.
+   */
+  set(elementId, annotation) {
+    const updated = {
+      ...annotation,
+      updatedAt: Date.now()
+    };
+    this.store.set(elementId, updated);
+    this.emit({
+      type: "annotation:set",
+      elementId,
+      annotation: updated,
+      timestamp: Date.now()
+    });
+  }
+  /**
+   * Delete an annotation by element ID.
+   *
+   * @returns true if the annotation existed and was deleted
+   */
+  delete(elementId) {
+    const existed = this.store.delete(elementId);
+    if (existed) {
+      this.emit({
+        type: "annotation:deleted",
+        elementId,
+        timestamp: Date.now()
+      });
+    }
+    return existed;
+  }
+  /**
+   * Check if an annotation exists for an element.
+   */
+  has(elementId) {
+    return this.store.has(elementId);
+  }
+  /**
+   * Get the number of stored annotations.
+   */
+  get count() {
+    return this.store.size;
+  }
+  /**
+   * Clear all annotations.
+   */
+  clear() {
+    this.store.clear();
+    this.emit({
+      type: "annotation:cleared",
+      timestamp: Date.now()
+    });
+  }
+  /**
+   * Import annotations from a config object.
+   *
+   * Merges with existing annotations (new values overwrite per element ID).
+   *
+   * @returns Number of annotations imported
+   *
+   * @example
+   * ```ts
+   * const config: AnnotationConfig = {
+   *   version: '1.0.0',
+   *   annotations: {
+   *     'btn-1': { description: 'Submit button', tags: ['form'] },
+   *     'input-1': { description: 'Name field' },
+   *   },
+   * };
+   * const count = store.importConfig(config); // 2
+   * ```
+   */
+  importConfig(config) {
+    let count = 0;
+    for (const [id, annotation] of Object.entries(config.annotations)) {
+      this.store.set(id, {
+        ...annotation,
+        updatedAt: annotation.updatedAt ?? Date.now()
+      });
+      count++;
+    }
+    this.emit({
+      type: "annotation:imported",
+      count,
+      timestamp: Date.now()
+    });
+    return count;
+  }
+  /**
+   * Export all annotations as a config object.
+   *
+   * The returned object can be serialized to JSON and saved to a file,
+   * then later re-imported with {@link importConfig}.
+   *
+   * @param metadata - Optional metadata to include (appName, description, etc.)
+   * @returns AnnotationConfig with all current annotations
+   *
+   * @example
+   * ```ts
+   * const config = store.exportConfig({ appName: 'MyApp' });
+   * // config.version === '1.0.0'
+   * // config.annotations === { 'btn-1': { ... }, 'input-1': { ... } }
+   * // config.metadata === { appName: 'MyApp', exportedAt: 1706900000000 }
+   *
+   * // Save to file
+   * fs.writeFileSync('annotations.json', JSON.stringify(config, null, 2));
+   * ```
+   */
+  exportConfig(metadata) {
+    return {
+      version: ANNOTATION_CONFIG_VERSION,
+      annotations: this.getAll(),
+      metadata: {
+        ...metadata,
+        exportedAt: Date.now()
+      }
+    };
+  }
+  /**
+   * Compute annotation coverage against a set of known element IDs.
+   *
+   * Compares the store's annotations against the provided list of element IDs
+   * to determine what percentage of elements have been annotated.
+   *
+   * @param allElementIds - Array of all known element IDs in the UI
+   * @returns Coverage statistics including percentages and lists of annotated/unannotated IDs
+   *
+   * @example
+   * ```ts
+   * store.set('btn-1', { description: 'Submit' });
+   * store.set('input-1', { description: 'Name' });
+   *
+   * const coverage = store.getCoverage(['btn-1', 'input-1', 'input-2', 'link-1']);
+   * // coverage.totalElements === 4
+   * // coverage.annotatedElements === 2
+   * // coverage.coveragePercent === 50
+   * // coverage.annotatedIds === ['btn-1', 'input-1']
+   * // coverage.unannotatedIds === ['input-2', 'link-1']
+   * ```
+   */
+  getCoverage(allElementIds) {
+    const annotatedIds = [];
+    const unannotatedIds = [];
+    for (const id of allElementIds) {
+      if (this.store.has(id)) {
+        annotatedIds.push(id);
+      } else {
+        unannotatedIds.push(id);
+      }
+    }
+    const total = allElementIds.length;
+    return {
+      totalElements: total,
+      annotatedElements: annotatedIds.length,
+      coveragePercent: total > 0 ? annotatedIds.length / total * 100 : 0,
+      annotatedIds,
+      unannotatedIds,
+      timestamp: Date.now()
+    };
+  }
+  /**
+   * Subscribe to annotation events.
+   *
+   * The listener is called whenever annotations are set, deleted, imported,
+   * or cleared. Returns an unsubscribe function to stop listening.
+   *
+   * @param listener - Callback function receiving {@link AnnotationEvent} objects
+   * @returns Unsubscribe function - call it to remove the listener
+   *
+   * @example
+   * ```ts
+   * const unsubscribe = store.on((event) => {
+   *   if (event.type === 'annotation:set') {
+   *     console.log(`Element ${event.elementId} annotated:`, event.annotation);
+   *   }
+   * });
+   *
+   * store.set('btn-1', { description: 'Submit' });
+   * // Logs: "Element btn-1 annotated: { description: 'Submit', updatedAt: ... }"
+   *
+   * unsubscribe(); // Stop listening
+   * ```
+   */
+  on(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  /**
+   * Emit an event to all listeners.
+   */
+  emit(event) {
+    for (const listener of this.listeners) {
+      try {
+        listener(event);
+      } catch {
+      }
+    }
+  }
+};
+var globalStore2 = null;
+function getGlobalAnnotationStore() {
+  if (!globalStore2) {
+    globalStore2 = new AnnotationStore();
+  }
+  return globalStore2;
+}
+
+// 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;
+      try {
+        tagName = element.element.tagName.toLowerCase();
+      } catch {
+        tagName = element.type || "unknown";
+      }
+      try {
+        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;
+      } catch {
+      }
+      if (!ariaLabel && element.label) {
+        ariaLabel = element.label;
+      }
+      try {
+        if (element.element.id) {
+          const labelEl = document.querySelector(`label[for="${element.element.id}"]`);
+          labelText = labelEl?.textContent?.trim() || void 0;
+        }
+      } catch {
+      }
+      if (!labelText && element.label) {
+        labelText = element.label;
+      }
+      if (!textContent && element.label) {
+        textContent = element.label;
+      }
+      try {
+        if (element.element instanceof HTMLInputElement || element.element instanceof HTMLTextAreaElement || element.element instanceof HTMLSelectElement) {
+          value = element.element.value || void 0;
+        }
+      } catch {
+        value = state.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;
+      if (!labelText && element.label) {
+        labelText = element.label;
+      }
+    }
+    let aliases = generateAliases({
+      textContent,
+      ariaLabel,
+      placeholder,
+      title,
+      elementType: element.type,
+      id: element.id,
+      labelText,
+      value
+    });
+    if ("aliases" in element && Array.isArray(element.aliases) && element.aliases.length > 0) {
+      const aliasSet = /* @__PURE__ */ new Set([
+        ...aliases,
+        ...element.aliases.map((a) => a.toLowerCase())
+      ]);
+      aliases = [...aliasSet];
+    }
+    let description = generateDescription({
+      textContent,
+      ariaLabel,
+      placeholder,
+      title,
+      elementType: element.type,
+      id: element.id,
+      labelText
+    });
+    if (!description && "description" in element && element.description) {
+      description = element.description;
+    }
+    const annotation = getGlobalAnnotationStore().get(element.id);
+    if (annotation) {
+      if (annotation.description) {
+        description = annotation.description;
+      }
+      if (annotation.tags && annotation.tags.length > 0) {
+        const tagSet = /* @__PURE__ */ new Set([...aliases, ...annotation.tags.map((t) => t.toLowerCase())]);
+        aliases = [...tagSet];
+      }
+      if (annotation.notes) {
+        aliases.push(annotation.notes.toLowerCase());
+      }
+    }
+    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.textContent && !criteria.text) {
+      const alternatives = criteria.textContent.includes("|") ? criteria.textContent.split("|").map((s) => s.trim()).filter(Boolean) : [criteria.textContent];
+      let bestScore = 0;
+      let bestReasons = [];
+      for (const alt of alternatives) {
+        const exactScore = this.scoreTextMatch(
+          searchable,
+          alt,
+          criteria.fuzzy !== false,
+          fuzzyConfig.threshold
+        );
+        const containsScore = this.scoreContainsMatch(searchable, alt, criteria.fuzzy !== false);
+        const altBest = Math.max(exactScore.score, containsScore.score);
+        if (altBest > bestScore) {
+          bestScore = altBest;
+          bestReasons = exactScore.score >= containsScore.score ? exactScore.reasons : containsScore.reasons;
+        }
+      }
+      scores.text = bestScore;
+      if (bestScore > 0) {
+        matchReasons.push(...bestReasons);
+      }
+      weightedScore += bestScore * 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/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 searchResult = this.findElementDetailed(request.target, request.fuzzy !== false);
+    const element = searchResult?.element ?? null;
+    const searchDetails = searchResult ? {
+      confidence: searchResult.confidence,
+      matchReasons: searchResult.matchReasons,
+      candidateCount: this.elements.length
+    } : void 0;
+    if (!element && request.type !== "notExists") {
+      const result2 = 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
+      );
+      if (searchDetails) {
+        result2.searchDetails = searchDetails;
+      }
+      return result2;
+    }
+    const result = await this.executeAssertion(request, element, timeout, startTime);
+    if (searchDetails) {
+      result.searchDetails = searchDetails;
+    }
+    return result;
+  }
+  /**
+   * 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 with full search metadata.
+   * Returns the SearchResult (including confidence, matchReasons, scores)
+   * or null if no match above the fuzzy threshold.
+   */
+  findElementDetailed(target, fuzzy = true) {
+    const criteria = typeof target === "string" ? { text: target, fuzzy } : { ...target, fuzzy };
+    const searchResult = this.searchEngine.findBest(criteria, this.elements);
+    if (searchResult && searchResult.confidence >= this.config.fuzzyThreshold) {
+      return searchResult;
+    }
+    return null;
+  }
+  /**
+   * Find element by target (string or criteria).
+   * Public for use by condition evaluation in SpecExecutor.
+   */
+  async findElement(target, fuzzy = true) {
+    const result = this.findElementDetailed(target, fuzzy);
+    return result?.element ?? 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/specs/executor.ts
+function resolveTarget(target) {
+  switch (target.type) {
+    case "elementId":
+      return { idPattern: target.elementId, fuzzy: false };
+    case "search":
+      return target.criteria;
+  }
+}
+var SpecExecutor = class {
+  constructor(config) {
+    this.assertionExecutor = new AssertionExecutor(config);
+  }
+  /**
+   * Update the element registry (pass-through to AssertionExecutor).
+   */
+  updateElements(elements) {
+    this.assertionExecutor.updateElements(elements);
+  }
+  /**
+   * Convert a SpecAssertion to an AssertionRequest.
+   */
+  toAssertionRequest(assertion) {
+    return {
+      target: resolveTarget(assertion.target),
+      type: assertion.assertionType,
+      expected: assertion.expected,
+      attributeName: assertion.attributeName,
+      propertyName: assertion.propertyName,
+      timeout: assertion.timeout,
+      message: assertion.message
+    };
+  }
+  /**
+   * Evaluate a condition to determine if an assertion should be executed.
+   * Returns true if the condition is met (assertion should run),
+   * false if condition is not met (assertion should skip/pass).
+   */
+  async evaluateCondition(condition) {
+    const target = resolveTarget(condition.target);
+    const element = await this.assertionExecutor.findElement(target, false);
+    switch (condition.type) {
+      case "exists":
+        return element !== null;
+      case "notExists":
+        return element === null;
+      case "hasText": {
+        if (!element) return false;
+        const textContent = element.state?.textContent || element.accessibleName || element.label || element.description || "";
+        return textContent.toLowerCase().includes(condition.text.toLowerCase());
+      }
+      default:
+        return true;
+    }
+  }
+  /**
+   * Execute a single SpecAssertion.
+   */
+  async executeAssertion(assertion) {
+    if (!assertion.enabled) {
+      return {
+        assertionId: assertion.id,
+        severity: assertion.severity,
+        category: assertion.category,
+        skipped: true,
+        result: null
+      };
+    }
+    if (assertion.condition) {
+      const conditionMet = await this.evaluateCondition(assertion.condition);
+      if (!conditionMet) {
+        return {
+          assertionId: assertion.id,
+          severity: assertion.severity,
+          category: assertion.category,
+          skipped: true,
+          skipReason: "condition_not_met",
+          result: null
+        };
+      }
+    }
+    const request = this.toAssertionRequest(assertion);
+    const result = await this.assertionExecutor.assert(request);
+    return {
+      assertionId: assertion.id,
+      severity: assertion.severity,
+      category: assertion.category,
+      skipped: false,
+      result
+    };
+  }
+  /**
+   * Execute all assertions in a SpecGroup.
+   */
+  async executeGroup(group, options) {
+    const startTime = Date.now();
+    const assertionResults = [];
+    let passedCount = 0;
+    let failedCount = 0;
+    let skippedCount = 0;
+    for (const assertion of group.assertions) {
+      if (shouldSkip(assertion, options)) {
+        assertionResults.push({
+          assertionId: assertion.id,
+          groupId: group.id,
+          severity: assertion.severity,
+          category: assertion.category,
+          skipped: true,
+          result: null
+        });
+        skippedCount++;
+        continue;
+      }
+      const result = await this.executeAssertion(assertion);
+      result.groupId = group.id;
+      assertionResults.push(result);
+      if (result.skipped) {
+        skippedCount++;
+      } else if (result.result?.passed) {
+        passedCount++;
+      } else {
+        failedCount++;
+        if (options?.stopOnFailure) break;
+      }
+    }
+    return {
+      groupId: group.id,
+      groupName: group.name,
+      assertionResults,
+      passedCount,
+      failedCount,
+      skippedCount,
+      passed: failedCount === 0,
+      durationMs: Date.now() - startTime,
+      timestamp: Date.now()
+    };
+  }
+  /**
+   * Execute a full SpecConfig.
+   */
+  async execute(config, options) {
+    const startTime = Date.now();
+    const groupResults = [];
+    for (const group of config.groups) {
+      if (options?.groupIds && !options.groupIds.includes(group.id)) continue;
+      const groupResult = await this.executeGroup(group, options);
+      groupResults.push(groupResult);
+      if (options?.stopOnFailure && !groupResult.passed) break;
+    }
+    const ungroupedResults = [];
+    if (config.assertions) {
+      for (const assertion of config.assertions) {
+        if (shouldSkip(assertion, options)) {
+          ungroupedResults.push({
+            assertionId: assertion.id,
+            severity: assertion.severity,
+            category: assertion.category,
+            skipped: true,
+            result: null
+          });
+          continue;
+        }
+        const result = await this.executeAssertion(assertion);
+        ungroupedResults.push(result);
+        if (options?.stopOnFailure && !result.skipped && !result.result?.passed) break;
+      }
+    }
+    let passedCount = 0;
+    let failedCount = 0;
+    let skippedCount = 0;
+    for (const gr of groupResults) {
+      passedCount += gr.passedCount;
+      failedCount += gr.failedCount;
+      skippedCount += gr.skippedCount;
+    }
+    for (const ur of ungroupedResults) {
+      if (ur.skipped) skippedCount++;
+      else if (ur.result?.passed) passedCount++;
+      else failedCount++;
+    }
+    return {
+      specVersion: config.version ?? SPEC_CONFIG_VERSION,
+      groupResults,
+      ungroupedResults,
+      totalAssertions: passedCount + failedCount + skippedCount,
+      passedCount,
+      failedCount,
+      skippedCount,
+      passed: failedCount === 0,
+      durationMs: Date.now() - startTime,
+      timestamp: Date.now()
+    };
+  }
+};
+function shouldSkip(assertion, options) {
+  if (!assertion.enabled) return true;
+  if (options?.assertionIds && !options.assertionIds.includes(assertion.id)) return true;
+  if (options?.categories && !options.categories.includes(assertion.category)) return true;
+  if (options?.severities && !options.severities.includes(assertion.severity)) return true;
+  if (options?.skipUnreviewed && !assertion.reviewed) return true;
+  return false;
+}
+
+exports.SPEC_CONFIG_VERSION = SPEC_CONFIG_VERSION;
+exports.SPEC_FILE_EXTENSION = SPEC_FILE_EXTENSION;
+exports.SpecExecutor = SpecExecutor;
+exports.SpecStore = SpecStore;
+exports.VALID_ASSERTION_TYPES = VALID_ASSERTION_TYPES;
+exports.VALID_SPEC_CATEGORIES = VALID_SPEC_CATEGORIES;
+exports.VALID_SPEC_SEVERITIES = VALID_SPEC_SEVERITIES;
+exports.VALID_SPEC_SOURCES = VALID_SPEC_SOURCES;
+exports.coerceAssertionType = coerceAssertionType;
+exports.getGlobalSpecStore = getGlobalSpecStore;
+exports.isValidAssertionType = isValidAssertionType;
+exports.isValidSpecCategory = isValidSpecCategory;
+exports.isValidSpecSeverity = isValidSpecSeverity;
+exports.isValidSpecSource = isValidSpecSource;
+exports.migrateFromTestGeneratorOutput = migrateFromTestGeneratorOutput;
+exports.migrateLegacyAssertion = migrateLegacyAssertion;
+exports.migrateLegacyTarget = migrateLegacyTarget;
+exports.resetGlobalSpecStore = resetGlobalSpecStore;
+exports.resolveTarget = resolveTarget;
+exports.validateSpecAssertion = validateSpecAssertion;
+exports.validateSpecConfig = validateSpecConfig;
+exports.validateSpecGroup = validateSpecGroup;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map