@qontinui/ui-bridge 0.3.0 → 0.3.1

package/dist/server/handlers.mjs

@@ -421,17 +421,72 @@ function generateDescription(input) {
     }
     parts.push(`"${name}"`);
   }
-  const typeWords = ELEMENT_ACTION_WORDS[input.elementType || ""] || [input.elementType || "element"];
+  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";
@@ -496,6 +551,10 @@ function generateSuggestedActions(input) {
   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"}"`);
@@ -543,6 +602,241 @@ function areSynonyms(word1, word2) {
   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 globalStore = null;
+function getGlobalAnnotationStore() {
+  if (!globalStore) {
+    globalStore = new AnnotationStore();
+  }
+  return globalStore;
+}
+
 // src/ai/search-engine.ts
 var DEFAULT_SEARCH_CONFIG = {
   fuzzyThreshold: 0.7,
@@ -585,17 +879,40 @@ var SearchEngine = class {
     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;
+      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;
@@ -604,8 +921,11 @@ var SearchEngine = class {
       tagName = discovered.tagName;
       role = discovered.role || void 0;
       ariaLabel = discovered.accessibleName || void 0;
+      if (!labelText && element.label) {
+        labelText = element.label;
+      }
     }
-    const aliases = generateAliases({
+    let aliases = generateAliases({
       textContent,
       ariaLabel,
       placeholder,
@@ -615,7 +935,14 @@ var SearchEngine = class {
       labelText,
       value
     });
-    const description = generateDescription({
+    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,
@@ -624,6 +951,22 @@ var SearchEngine = class {
       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,
@@ -726,7 +1069,12 @@ var SearchEngine = class {
       threshold: criteria.fuzzyThreshold ?? this.config.fuzzyThreshold
     };
     if (criteria.text) {
-      const textScore = this.scoreTextMatch(searchable, criteria.text, criteria.fuzzy !== false, fuzzyConfig.threshold);
+      const textScore = this.scoreTextMatch(
+        searchable,
+        criteria.text,
+        criteria.fuzzy !== false,
+        fuzzyConfig.threshold
+      );
       scores.text = textScore.score;
       if (textScore.score > 0) {
         matchReasons.push(...textScore.reasons);
@@ -734,8 +1082,37 @@ var SearchEngine = class {
       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);
+      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);
@@ -784,7 +1161,11 @@ var SearchEngine = class {
       totalWeight += this.config.spatialWeight;
     }
     if (criteria.placeholder && searchable.placeholder) {
-      const placeholderResult = fuzzyMatch(searchable.placeholder, criteria.placeholder, fuzzyConfig);
+      const placeholderResult = fuzzyMatch(
+        searchable.placeholder,
+        criteria.placeholder,
+        fuzzyConfig
+      );
       if (placeholderResult.isMatch) {
         matchReasons.push(`placeholder matches`);
         weightedScore += placeholderResult.similarity * this.config.textWeight;
@@ -829,11 +1210,9 @@ var SearchEngine = class {
   scoreTextMatch(searchable, text, fuzzy, threshold) {
     const reasons = [];
     let maxScore = 0;
-    const textsToMatch = [
-      searchable.textContent,
-      searchable.labelText,
-      searchable.value
-    ].filter(Boolean);
+    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);
@@ -929,7 +1308,9 @@ var SearchEngine = class {
       heading: ["h1", "h2", "h3", "h4", "h5", "h6"]
     };
     const inferredRoles = tagRoleMap[normalizedRole] || [];
-    if (inferredRoles.some((r) => searchable.tagName === r || searchable.type.toLowerCase() === normalizedRole)) {
+    if (inferredRoles.some(
+      (r) => searchable.tagName === r || searchable.type.toLowerCase() === normalizedRole
+    )) {
       return { score: 0.8, reasons: [`inferred role: ${role}`] };
     }
     return { score: 0, reasons };
@@ -1116,11 +1497,14 @@ function generatePageSummary(elements, pageContext, config = {}) {
   if (finalConfig.includeElementCounts) {
     const counts = countElementTypes(elements);
     const countParts = [];
-    if (counts.button > 0) countParts.push(`${counts.button} button${counts.button > 1 ? "s" : ""}`);
+    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 (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(", ")}`);
     }
@@ -1163,7 +1547,9 @@ function generateFormSummary(form, verbosity) {
   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"}`);
+    lines.push(
+      `    ${filledCount}/${fieldCount} fields filled, ${form.isValid ? "valid" : "has errors"}`
+    );
   } else {
     for (const field of form.fields) {
       let fieldLine = `    - ${field.label || field.id}`;
@@ -1198,7 +1584,9 @@ function generateDiffSummary(appeared, disappeared, modified) {
   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}"`);
+      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`);
@@ -1629,7 +2017,9 @@ function parseNLInstruction(instruction) {
         }
       }
       if (pattern.action === "assert") {
-        const assertMatch = trimmed.match(/(visible|hidden|enabled|disabled|checked|unchecked|focused|contains|has)/i);
+        const assertMatch = trimmed.match(
+          /(visible|hidden|enabled|disabled|checked|unchecked|focused|contains|has)/i
+        );
         if (assertMatch) {
           parsed.assertionType = ASSERTION_TYPE_MAP[assertMatch[1].toLowerCase()];
         }
@@ -2390,7 +2780,9 @@ var NLActionExecutor = class {
     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"');
+        suggestions.push(
+          'Ensure the instruction follows patterns like "click X" or "type Y into X"'
+        );
         break;
       case "ELEMENT_NOT_FOUND":
         if (alternatives.length > 0) {
@@ -2458,9 +2850,15 @@ var AssertionExecutor = class {
   async assert(request) {
     const startTime = performance.now();
     const timeout = request.timeout ?? this.config.defaultTimeout;
-    const element = await this.findElement(request.target, request.fuzzy !== false);
+    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") {
-      return this.createResult(
+      const result2 = this.createResult(
         false,
         typeof request.target === "string" ? request.target : JSON.stringify(request.target),
         "element not found",
@@ -2470,8 +2868,16 @@ var AssertionExecutor = class {
         this.config.includeSuggestions ? "Check if the element exists and is properly labeled" : void 0,
         startTime
       );
+      if (searchDetails) {
+        result2.searchDetails = searchDetails;
+      }
+      return result2;
     }
-    return this.executeAssertion(request, element, timeout, startTime);
+    const result = await this.executeAssertion(request, element, timeout, startTime);
+    if (searchDetails) {
+      result.searchDetails = searchDetails;
+    }
+    return result;
   }
   /**
    * Execute multiple assertions
@@ -2576,16 +2982,26 @@ var AssertionExecutor = class {
     return this.assert({ target, type: "count", expected: expectedCount, timeout });
   }
   /**
-   * Find element by target (string or criteria)
+   * Find element by target with full search metadata.
+   * Returns the SearchResult (including confidence, matchReasons, scores)
+   * or null if no match above the fuzzy threshold.
    */
-  async findElement(target, fuzzy = true) {
+  findElementDetailed(target, fuzzy = true) {
     const criteria = typeof target === "string" ? { text: target, fuzzy } : { ...target, fuzzy };
-    const searchResult = this.searchEngine.findBest(criteria);
+    const searchResult = this.searchEngine.findBest(criteria, this.elements);
     if (searchResult && searchResult.confidence >= this.config.fuzzyThreshold) {
-      return searchResult.element;
+      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
    */
@@ -2594,19 +3010,55 @@ var AssertionExecutor = class {
     const elementDescription = element?.description || targetStr;
     switch (request.type) {
       case "visible":
-        return this.assertVisibility(element, true, elementDescription, request.message, startTime);
+        return this.assertVisibility(
+          element,
+          true,
+          elementDescription,
+          request.message,
+          startTime
+        );
       case "hidden":
-        return this.assertVisibility(element, false, elementDescription, request.message, startTime);
+        return this.assertVisibility(
+          element,
+          false,
+          elementDescription,
+          request.message,
+          startTime
+        );
       case "enabled":
-        return this.assertEnabledState(element, true, elementDescription, request.message, startTime);
+        return this.assertEnabledState(
+          element,
+          true,
+          elementDescription,
+          request.message,
+          startTime
+        );
       case "disabled":
-        return this.assertEnabledState(element, false, elementDescription, request.message, startTime);
+        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);
+        return this.assertCheckedState(
+          element,
+          true,
+          elementDescription,
+          request.message,
+          startTime
+        );
       case "unchecked":
-        return this.assertCheckedState(element, false, elementDescription, request.message, startTime);
+        return this.assertCheckedState(
+          element,
+          false,
+          elementDescription,
+          request.message,
+          startTime
+        );
       case "hasText":
         return this.assertTextMatch(
           element,
@@ -2941,7 +3393,8 @@ var DEFAULT_SNAPSHOT_CONFIG = {
   detectModals: true,
   inferPageType: true,
   generateDescriptions: true,
-  maxElements: 500
+  maxElements: 500,
+  useAnnotations: true
 };
 var SemanticSnapshotManager = class {
   constructor(config = {}) {
@@ -3014,26 +3467,52 @@ var SemanticSnapshotManager = class {
    * Convert a single element to AI element
    */
   convertElement(element) {
+    const isContent = element.category === "content";
     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({
+    let description;
+    if (isContent && element.contentMetadata) {
+      description = this.generateContentDescription(element);
+    } else if (this.config.generateDescriptions) {
+      description = generateDescription({
+        textContent: element.state.textContent,
+        elementType: element.type,
+        id: element.id,
+        labelText: element.label
+      });
+    } else {
+      description = element.label || element.id;
+    }
+    const purpose = isContent ? generatePurpose({ textContent: element.state.textContent, elementType: element.type }) : generatePurpose({ textContent: element.state.textContent, elementType: element.type });
+    const suggestedActions = isContent ? generateSuggestedActions({
       textContent: element.state.textContent,
       elementType: element.type
-    });
-    const suggestedActions = generateSuggestedActions({
+    }) : generateSuggestedActions({
       textContent: element.state.textContent,
       elementType: element.type
     });
+    let finalDescription = description;
+    let finalPurpose = purpose;
+    let finalAliases = aliases;
+    if (this.config.useAnnotations) {
+      const annotation = getGlobalAnnotationStore().get(element.id);
+      if (annotation) {
+        if (annotation.description) {
+          finalDescription = annotation.description;
+        }
+        if (annotation.purpose) {
+          finalPurpose = annotation.purpose;
+        }
+        if (annotation.tags && annotation.tags.length > 0) {
+          const tagSet = /* @__PURE__ */ new Set([...finalAliases, ...annotation.tags.map((t) => t.toLowerCase())]);
+          finalAliases = [...tagSet];
+        }
+      }
+    }
     return {
       id: element.id,
       type: element.type,
@@ -3044,13 +3523,56 @@ var SemanticSnapshotManager = class {
       actions: element.actions,
       state: element.state,
       registered: true,
-      description,
-      aliases,
-      purpose,
+      description: finalDescription,
+      aliases: finalAliases,
+      purpose: finalPurpose,
       suggestedActions,
-      semanticType: this.inferSemanticType(element)
+      semanticType: this.inferSemanticType(element),
+      category: element.category,
+      contentMetadata: element.contentMetadata
     };
   }
+  /**
+   * Generate a content-specific description
+   */
+  generateContentDescription(element) {
+    const meta = element.contentMetadata;
+    const text = element.state.textContent?.trim() || "";
+    const truncatedText = text.length > 60 ? text.substring(0, 57) + "..." : text;
+    if (!meta) return `"${truncatedText}"`;
+    switch (meta.contentRole) {
+      case "heading":
+        return `Level ${meta.headingLevel || "?"} heading: '${truncatedText}'`;
+      case "table-cell":
+        return `Table cell${meta.structuralContext ? ` (${meta.structuralContext})` : ""}: '${truncatedText}'`;
+      case "table-header":
+        return `Table header${meta.structuralContext ? ` (${meta.structuralContext})` : ""}: '${truncatedText}'`;
+      case "status":
+        return `Status message: '${truncatedText}'`;
+      case "badge":
+        return `Badge: '${truncatedText}'`;
+      case "metric":
+        return `Metric value: '${truncatedText}'`;
+      case "body-text":
+        return `Text: '${truncatedText}'`;
+      case "list-item":
+        return `List item: '${truncatedText}'`;
+      case "quote":
+        return `Blockquote: '${truncatedText}'`;
+      case "code":
+        return `Code block: '${truncatedText}'`;
+      case "caption":
+        return `Caption: '${truncatedText}'`;
+      case "label":
+        return `Label: '${truncatedText}'`;
+      case "description":
+        return `Description: '${truncatedText}'`;
+      case "navigation":
+        return `Navigation text: '${truncatedText}'`;
+      default:
+        return `Content: '${truncatedText}'`;
+    }
+  }
   /**
    * Build full page context
    */
@@ -3154,9 +3676,7 @@ var SemanticSnapshotManager = class {
    */
   detectModals(elements) {
     const modals = [];
-    const dialogElements = elements.filter(
-      (el) => el.type === "dialog" && el.state.visible
-    );
+    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/))
@@ -3207,9 +3727,7 @@ var SemanticSnapshotManager = class {
    * Infer form purpose from fields
    */
   inferFormPurpose(fields) {
-    const labels = fields.map(
-      (f) => (f.accessibleName || f.label || "").toLowerCase()
-    );
+    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")) {
@@ -3263,6 +3781,13 @@ var SemanticSnapshotManager = class {
    * Infer semantic type
    */
   inferSemanticType(element) {
+    if (element.category === "content" && element.contentMetadata) {
+      const role = element.contentMetadata.contentRole;
+      if (role === "heading" && element.contentMetadata.headingLevel) {
+        return `heading-${element.contentMetadata.headingLevel}`;
+      }
+      return role;
+    }
     const text = (element.state.textContent || element.label || "").toLowerCase();
     const type = element.type.toLowerCase();
     if (type === "button") {
@@ -3344,6 +3869,7 @@ function computeDiff(fromSnapshot, toSnapshot, config = {}) {
   const probableTrigger = detectTrigger(appeared, disappeared, limitedModifications);
   const suggestedActions = finalConfig.generateSuggestions ? generateSuggestedActionsFromDiff(appeared, disappeared, limitedModifications, probableTrigger) : void 0;
   const pageChanges = detectPageChanges(fromSnapshot, toSnapshot);
+  const contentChanges = detectContentChanges(fromElements, toElements);
   const summary = generateDiffSummary(
     appeared.map((e) => e.description),
     disappeared.map((e) => e.description),
@@ -3358,6 +3884,7 @@ function computeDiff(fromSnapshot, toSnapshot, config = {}) {
       disappeared,
       modified: limitedModifications
     },
+    contentChanges: contentChanges || void 0,
     probableTrigger,
     suggestedActions,
     pageChanges,
@@ -3492,9 +4019,7 @@ function generateSuggestedActionsFromDiff(appeared, disappeared, modified, trigg
     suggestions.push("Fix the validation errors before submitting");
   }
   if (trigger === "Modal opened") {
-    const modal = appeared.find(
-      (e) => e.type === "dialog" || e.semanticType?.includes("dialog")
-    );
+    const modal = appeared.find((e) => e.type === "dialog" || e.semanticType?.includes("dialog"));
     if (modal) {
       suggestions.push(`Interact with the "${modal.description}" dialog`);
     }
@@ -3557,76 +4082,1869 @@ var SemanticDiffManager = class {
     return this.lastSnapshot;
   }
 };
-
-// src/server/handlers.ts
-function success(data) {
-  return {
-    success: true,
-    data,
-    timestamp: Date.now()
-  };
+var METRIC_CONTENT_TYPES = /* @__PURE__ */ new Set(["metric-value"]);
+var STATUS_CONTENT_TYPES = /* @__PURE__ */ new Set(["status-message", "badge"]);
+var HEADING_CONTENT_TYPES = /* @__PURE__ */ new Set(["heading"]);
+function isContentElement(element) {
+  return element.category === "content" || element.contentMetadata !== void 0;
 }
-function error(message, code) {
+function getContentType(element) {
+  if (element.contentMetadata?.contentRole) {
+    return element.contentMetadata.contentRole;
+  }
+  return element.type;
+}
+function detectContentChanges(fromElements, toElements) {
+  const textChanges = [];
+  const metricChanges = [];
+  const statusChanges = [];
+  for (const [id, toElement] of toElements) {
+    const fromElement = fromElements.get(id);
+    if (fromElement) {
+      if (isContentElement(toElement) || isContentElement(fromElement)) {
+        const fromText = (fromElement.state.textContent || "").trim();
+        const toText = (toElement.state.textContent || "").trim();
+        if (fromText !== toText) {
+          const contentType = getContentType(toElement);
+          const label = toElement.description || toElement.accessibleName || id;
+          if (METRIC_CONTENT_TYPES.has(contentType) || contentType === "metric") {
+            const parsed = parseMetricChange(fromText, toText, id, label);
+            if (parsed) {
+              metricChanges.push(parsed);
+            }
+          } else if (STATUS_CONTENT_TYPES.has(contentType) || contentType === "status") {
+            statusChanges.push({
+              elementId: id,
+              label,
+              oldStatus: fromText,
+              newStatus: toText,
+              direction: classifyStatusDirection(fromText, toText)
+            });
+          } else {
+            textChanges.push({
+              elementId: id,
+              contentType,
+              oldText: fromText,
+              newText: toText,
+              changeType: "modified"
+            });
+          }
+        }
+      }
+    } else {
+      if (isContentElement(toElement)) {
+        const toText = (toElement.state.textContent || "").trim();
+        if (toText) {
+          textChanges.push({
+            elementId: id,
+            contentType: getContentType(toElement),
+            oldText: "",
+            newText: toText,
+            changeType: "added"
+          });
+        }
+      }
+    }
+  }
+  for (const [id, fromElement] of fromElements) {
+    if (!toElements.has(id) && isContentElement(fromElement)) {
+      const fromText = (fromElement.state.textContent || "").trim();
+      if (fromText) {
+        textChanges.push({
+          elementId: id,
+          contentType: getContentType(fromElement),
+          oldText: fromText,
+          newText: "",
+          changeType: "removed"
+        });
+      }
+    }
+  }
+  if (textChanges.length === 0 && metricChanges.length === 0 && statusChanges.length === 0) {
+    return null;
+  }
   return {
-    success: false,
-    error: message,
-    code,
-    timestamp: Date.now()
+    textChanges,
+    metricChanges,
+    statusChanges,
+    summary: generateContentChangeSummary(textChanges, metricChanges, statusChanges)
   };
 }
-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 parseNumericValue(text) {
+  const trimmed = text.trim();
+  if (!trimmed) return null;
+  let working = trimmed;
+  let negate = false;
+  if (working.startsWith("(") && working.endsWith(")")) {
+    working = working.slice(1, -1).trim();
+    negate = true;
+  }
+  if (working.startsWith("-")) {
+    negate = !negate;
+    working = working.slice(1).trim();
+  }
+  if (working.startsWith("+")) {
+    working = working.slice(1).trim();
+  }
+  working = working.replace(/^[£€¥₹$]/, "").trim();
+  const isPercent = working.endsWith("%");
+  if (isPercent) {
+    working = working.slice(0, -1).trim();
+  }
+  working = working.replace(/\s*(ms|s|m|h|d|hrs?|mins?|secs?|days?)$/i, "").trim();
+  working = working.replace(/,/g, "");
+  const num = Number(working);
+  if (isNaN(num) || !isFinite(num) || working === "") {
+    return null;
   }
+  return negate ? -num : num;
 }
-function createFailureDetails(errorCode, message, options = {}) {
-  const retryableErrors = [
-    "ELEMENT_NOT_VISIBLE",
+function parseMetricChange(fromText, toText, elementId, label) {
+  const fromNum = parseNumericValue(fromText);
+  const toNum = parseNumericValue(toText);
+  let numericDelta;
+  let percentChange;
+  let significant = false;
+  if (fromNum !== null && toNum !== null) {
+    numericDelta = toNum - fromNum;
+    if (fromNum !== 0) {
+      percentChange = (toNum - fromNum) / Math.abs(fromNum) * 100;
+    }
+    if (percentChange !== void 0 && Math.abs(percentChange) > 10) {
+      significant = true;
+    }
+    if (fromNum > 0 && toNum < 0) significant = true;
+    if (fromNum < 0 && toNum > 0) significant = true;
+    if (fromNum === 0 && toNum !== 0) significant = true;
+    if (fromNum !== 0 && toNum === 0) significant = true;
+  } else {
+    significant = fromText !== toText;
+  }
+  return {
+    elementId,
+    label,
+    oldValue: fromText,
+    newValue: toText,
+    numericDelta,
+    percentChange: percentChange !== void 0 ? Math.round(percentChange * 100) / 100 : void 0,
+    significant
+  };
+}
+var STATUS_PROGRESSIONS = [
+  [
+    "failed",
+    "error",
+    "pending",
+    "queued",
+    "running",
+    "in progress",
+    "completed",
+    "success",
+    "done"
+  ],
+  ["disconnected", "connecting", "connected"],
+  ["unhealthy", "degraded", "healthy"],
+  ["offline", "online"],
+  ["inactive", "active"],
+  ["disabled", "enabled"],
+  ["down", "up"],
+  ["stopped", "starting", "started", "running"],
+  ["closed", "open"],
+  ["blocked", "unblocked"],
+  ["rejected", "pending", "approved"],
+  ["critical", "warning", "info", "ok"],
+  ["red", "yellow", "green"]
+];
+function classifyStatusDirection(oldStatus, newStatus) {
+  const oldLower = oldStatus.toLowerCase().trim();
+  const newLower = newStatus.toLowerCase().trim();
+  for (const progression of STATUS_PROGRESSIONS) {
+    let oldIndex = -1;
+    let newIndex = -1;
+    for (let i = 0; i < progression.length; i++) {
+      if (oldLower.includes(progression[i])) oldIndex = i;
+      if (newLower.includes(progression[i])) newIndex = i;
+    }
+    if (oldIndex >= 0 && newIndex >= 0 && oldIndex !== newIndex) {
+      return newIndex > oldIndex ? "improved" : "degraded";
+    }
+  }
+  return "neutral";
+}
+function generateContentChangeSummary(textChanges, metricChanges, statusChanges) {
+  const parts = [];
+  const modified = textChanges.filter((t) => t.changeType === "modified").length;
+  const added = textChanges.filter((t) => t.changeType === "added").length;
+  const removed = textChanges.filter((t) => t.changeType === "removed").length;
+  const headingChanges = textChanges.filter(
+    (t) => HEADING_CONTENT_TYPES.has(t.contentType) || t.contentType === "heading"
+  );
+  if (headingChanges.length > 0) {
+    parts.push(`${headingChanges.length} heading${headingChanges.length > 1 ? "s" : ""} changed`);
+  }
+  if (metricChanges.length > 0) {
+    const significantMetrics = metricChanges.filter((m) => m.significant);
+    if (significantMetrics.length > 0) {
+      parts.push(
+        `${significantMetrics.length} metric${significantMetrics.length > 1 ? "s" : ""} changed significantly`
+      );
+    } else {
+      parts.push(`${metricChanges.length} metric${metricChanges.length > 1 ? "s" : ""} changed`);
+    }
+  }
+  if (statusChanges.length > 0) {
+    const degraded = statusChanges.filter((s) => s.direction === "degraded");
+    const improved = statusChanges.filter((s) => s.direction === "improved");
+    if (degraded.length > 0) {
+      parts.push(`${degraded.length} status${degraded.length > 1 ? "es" : ""} degraded`);
+    }
+    if (improved.length > 0) {
+      parts.push(`${improved.length} status${improved.length > 1 ? "es" : ""} improved`);
+    }
+    const neutral = statusChanges.length - degraded.length - improved.length;
+    if (neutral > 0 && degraded.length === 0 && improved.length === 0) {
+      parts.push(`${neutral} status${neutral > 1 ? "es" : ""} changed`);
+    }
+  }
+  const otherModified = modified - headingChanges.filter((h) => h.changeType === "modified").length;
+  if (otherModified > 0) {
+    parts.push(`${otherModified} text${otherModified > 1 ? " values" : " value"} modified`);
+  }
+  if (added > 0) {
+    parts.push(`${added} content${added > 1 ? " elements" : " element"} added`);
+  }
+  if (removed > 0) {
+    parts.push(`${removed} content${removed > 1 ? " elements" : " element"} removed`);
+  }
+  if (parts.length === 0) {
+    return "No content changes";
+  }
+  return parts.join(", ");
+}
+
+// src/ai/data-extraction.ts
+var DEFAULT_DATA_EXTRACTION_CONFIG = {
+  minConfidence: 0.3,
+  normalizeWhitespace: true
+};
+function classifyDataType(value) {
+  const trimmed = value.trim();
+  if (!trimmed) return { type: "unknown", confidence: 0 };
+  if (/^(true|false|yes|no|on|off)$/i.test(trimmed)) {
+    return { type: "boolean", confidence: 0.95 };
+  }
+  if (/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(trimmed)) {
+    return { type: "email", confidence: 0.95 };
+  }
+  if (/^https?:\/\/\S+/.test(trimmed)) {
+    return { type: "url", confidence: 0.95 };
+  }
+  if (/^[+]?[\d\s\-().]{7,20}$/.test(trimmed) && /\d{3,}/.test(trimmed)) {
+    return { type: "phone", confidence: 0.7 };
+  }
+  if (/^[£$€¥₹][\s]?[\d,.]+$/.test(trimmed) || /^[\d,.]+[\s]?[£$€¥₹]$/.test(trimmed)) {
+    return { type: "currency", confidence: 0.9 };
+  }
+  if (/^[\d,.]+\s?%$/.test(trimmed)) {
+    return { type: "percentage", confidence: 0.95 };
+  }
+  if (/^\d{4}-\d{2}-\d{2}/.test(trimmed) || /^\d{1,2}\/\d{1,2}\/\d{2,4}$/.test(trimmed) || /^\d{1,2}\.\d{1,2}\.\d{2,4}$/.test(trimmed) || /^\w{3,9}\s+\d{1,2},?\s+\d{4}$/.test(trimmed)) {
+    return { type: "date", confidence: 0.85 };
+  }
+  if (/^-?[\d,]+\.?\d*$/.test(trimmed) && trimmed !== "") {
+    return { type: "number", confidence: 0.9 };
+  }
+  return { type: "text", confidence: 0.5 };
+}
+function normalizeValue(value, dataType) {
+  const trimmed = value.trim();
+  switch (dataType) {
+    case "number":
+    case "currency":
+    case "percentage": {
+      const numeric = trimmed.replace(/[^0-9.-]/g, "");
+      const parsed = parseFloat(numeric);
+      return isNaN(parsed) ? trimmed.toLowerCase() : parsed.toString();
+    }
+    case "date": {
+      const d = new Date(trimmed);
+      return isNaN(d.getTime()) ? trimmed.toLowerCase() : d.toISOString().split("T")[0];
+    }
+    case "boolean":
+      return /^(true|yes|on)$/i.test(trimmed) ? "true" : "false";
+    case "email":
+      return trimmed.toLowerCase();
+    case "url":
+      return trimmed.replace(/\/+$/, "").toLowerCase();
+    case "phone":
+      return trimmed.replace(/[^\d+]/g, "");
+    default:
+      return trimmed.toLowerCase().replace(/\s+/g, " ");
+  }
+}
+function extractElementValue(element) {
+  const state = element.state;
+  if (state?.value !== void 0 && state.value !== "") {
+    return String(state.value);
+  }
+  if (state?.textContent !== void 0 && state.textContent !== "") {
+    return String(state.textContent);
+  }
+  return "";
+}
+function extractLabel(element) {
+  return element.accessibleName || element.labelText || element.label || element.description || element.id;
+}
+function extractPageData(elements, config = DEFAULT_DATA_EXTRACTION_CONFIG) {
+  const values = {};
+  let extractedCount = 0;
+  for (const element of elements) {
+    const rawValue = extractElementValue(element);
+    if (!rawValue) continue;
+    const label = extractLabel(element);
+    const { type: dataType, confidence } = classifyDataType(rawValue);
+    if (confidence < config.minConfidence) continue;
+    const normalizedValue = normalizeValue(rawValue, dataType);
+    values[label] = {
+      elementId: element.id,
+      label,
+      rawValue: config.normalizeWhitespace ? rawValue.replace(/\s+/g, " ").trim() : rawValue,
+      normalizedValue,
+      dataType,
+      confidence
+    };
+    extractedCount++;
+  }
+  return {
+    values,
+    scannedCount: elements.length,
+    extractedCount
+  };
+}
+
+// src/ai/region-segmentation.ts
+var DEFAULT_REGION_SEGMENTATION_CONFIG = {
+  minRegionElements: 1,
+  headerFraction: 0.12,
+  footerFraction: 0.9,
+  sidebarFraction: 0.2
+};
+function toBounded(el) {
+  const rect = el.state?.rect;
+  if (!rect) return null;
+  return {
+    element: el,
+    x: rect.x ?? 0,
+    y: rect.y ?? 0,
+    width: rect.width ?? 0,
+    height: rect.height ?? 0
+  };
+}
+function classifyRegionType(el, relativeY, relativeX, config = DEFAULT_REGION_SEGMENTATION_CONFIG) {
+  const role = (el.role || "").toLowerCase();
+  const semanticType = (el.semanticType || "").toLowerCase();
+  const tag = (el.tagName || "").toLowerCase();
+  if (role === "navigation" || role === "nav" || tag === "nav") {
+    return { type: "navigation", confidence: 0.95 };
+  }
+  if (role === "banner" || tag === "header") {
+    return { type: "header", confidence: 0.95 };
+  }
+  if (role === "contentinfo" || tag === "footer") {
+    return { type: "footer", confidence: 0.95 };
+  }
+  if (role === "main" || tag === "main") {
+    return { type: "main-content", confidence: 0.95 };
+  }
+  if (role === "complementary" || tag === "aside") {
+    return { type: "sidebar", confidence: 0.9 };
+  }
+  if (role === "form" || tag === "form") {
+    return { type: "form", confidence: 0.9 };
+  }
+  if (role === "table" || tag === "table") {
+    return { type: "table", confidence: 0.9 };
+  }
+  if (role === "dialog" || role === "alertdialog") {
+    return { type: "modal", confidence: 0.95 };
+  }
+  if (role === "toolbar") {
+    return { type: "toolbar", confidence: 0.9 };
+  }
+  if (semanticType.includes("card")) {
+    return { type: "card", confidence: 0.8 };
+  }
+  if (relativeY < config.headerFraction) {
+    return { type: "header", confidence: 0.6 };
+  }
+  if (relativeY > config.footerFraction) {
+    return { type: "footer", confidence: 0.6 };
+  }
+  if (relativeX < config.sidebarFraction) {
+    return { type: "sidebar", confidence: 0.5 };
+  }
+  return { type: "main-content", confidence: 0.3 };
+}
+function segmentPageRegions(elements, config = DEFAULT_REGION_SEGMENTATION_CONFIG) {
+  const bounded = elements.map(toBounded).filter((b) => b !== null);
+  if (bounded.length === 0) {
+    return { regions: [], assignedCount: 0, unassignedIds: elements.map((e) => e.id) };
+  }
+  let maxX = 0;
+  let maxY = 0;
+  for (const b of bounded) {
+    maxX = Math.max(maxX, b.x + b.width);
+    maxY = Math.max(maxY, b.y + b.height);
+  }
+  if (maxX === 0) maxX = 1;
+  if (maxY === 0) maxY = 1;
+  const regionGroups = /* @__PURE__ */ new Map();
+  const unassignedIds = [];
+  for (const b of bounded) {
+    const relativeX = b.x / maxX;
+    const relativeY = b.y / maxY;
+    const { type, confidence } = classifyRegionType(b.element, relativeY, relativeX, config);
+    if (!regionGroups.has(type)) {
+      regionGroups.set(type, { elements: [], confidences: [] });
+    }
+    regionGroups.get(type).elements.push(b);
+    regionGroups.get(type).confidences.push(confidence);
+  }
+  const regions = [];
+  let assignedCount = 0;
+  for (const [type, group] of regionGroups) {
+    if (group.elements.length < config.minRegionElements) {
+      for (const b of group.elements) unassignedIds.push(b.element.id);
+      continue;
+    }
+    let minX = Infinity, minY = Infinity, maxRX = 0, maxRY = 0;
+    const elementIds = [];
+    for (const b of group.elements) {
+      minX = Math.min(minX, b.x);
+      minY = Math.min(minY, b.y);
+      maxRX = Math.max(maxRX, b.x + b.width);
+      maxRY = Math.max(maxRY, b.y + b.height);
+      elementIds.push(b.element.id);
+    }
+    const avgConfidence = group.confidences.reduce((a, b) => a + b, 0) / group.confidences.length;
+    regions.push({
+      type,
+      bounds: { x: minX, y: minY, width: maxRX - minX, height: maxRY - minY },
+      elementIds,
+      label: type.replace("-", " ").replace(/\b\w/g, (c) => c.toUpperCase()),
+      confidence: Math.round(avgConfidence * 100) / 100
+    });
+    assignedCount += elementIds.length;
+  }
+  return { regions, assignedCount, unassignedIds };
+}
+
+// src/ai/table-extraction.ts
+var DEFAULT_TABLE_EXTRACTION_CONFIG = {
+  minTableColumns: 2,
+  minTableRows: 2,
+  minListItems: 2,
+  columnTolerance: 20,
+  rowTolerance: 10
+};
+function getElementBounds(el) {
+  const rect = el.state?.rect;
+  if (!rect || rect.width === 0) return null;
+  const text = el.state?.textContent ?? el.state?.value ?? "";
+  if (!text) return null;
+  return {
+    element: el,
+    x: rect.x ?? 0,
+    y: rect.y ?? 0,
+    width: rect.width ?? 0,
+    height: rect.height ?? 0,
+    text: text.trim()
+  };
+}
+function clusterPositions(values, tolerance) {
+  if (values.length === 0) return [];
+  const sorted = [...values].sort((a, b) => a - b);
+  const clusters = [sorted[0]];
+  for (let i = 1; i < sorted.length; i++) {
+    if (sorted[i] - clusters[clusters.length - 1] > tolerance) {
+      clusters.push(sorted[i]);
+    }
+  }
+  return clusters;
+}
+function assignToCluster(value, clusters, tolerance) {
+  let best = 0;
+  let bestDist = Math.abs(value - clusters[0]);
+  for (let i = 1; i < clusters.length; i++) {
+    const dist = Math.abs(value - clusters[i]);
+    if (dist < bestDist) {
+      bestDist = dist;
+      best = i;
+    }
+  }
+  return bestDist <= tolerance ? best : -1;
+}
+function detectTable(elements, config = DEFAULT_TABLE_EXTRACTION_CONFIG) {
+  const withBounds = elements.map(getElementBounds).filter((b) => b !== null);
+  if (withBounds.length < config.minTableColumns * config.minTableRows) return null;
+  const xPositions = withBounds.map((b) => b.x);
+  const yPositions = withBounds.map((b) => b.y);
+  const columnClusters = clusterPositions(xPositions, config.columnTolerance);
+  const rowClusters = clusterPositions(yPositions, config.rowTolerance);
+  if (columnClusters.length < config.minTableColumns || rowClusters.length < config.minTableRows) {
+    return null;
+  }
+  const grid = Array.from(
+    { length: rowClusters.length },
+    () => Array(columnClusters.length).fill(null)
+  );
+  for (const b of withBounds) {
+    const col = assignToCluster(b.x, columnClusters, config.columnTolerance);
+    const row = assignToCluster(b.y, rowClusters, config.rowTolerance);
+    if (col >= 0 && row >= 0 && grid[row][col] === null) {
+      grid[row][col] = b.text;
+    }
+  }
+  const headers = grid[0].map((h) => h ?? "");
+  const columns = headers.map((header, index) => {
+    const bodyCells = grid.slice(1).map((r) => r[index]).filter((c) => c !== null);
+    const types = bodyCells.map((c) => classifyDataType(c).type);
+    const mostCommon = mode(types) ?? "text";
+    return { header, index, dataType: mostCommon };
+  });
+  const rows = grid.slice(1).map((row) => row.map((cell) => cell ?? ""));
+  return {
+    label: headers[0] || "Table",
+    columns,
+    rows
+  };
+}
+function detectList(elements, config = DEFAULT_TABLE_EXTRACTION_CONFIG) {
+  const withBounds = elements.map(getElementBounds).filter((b) => b !== null);
+  if (withBounds.length < config.minListItems) return null;
+  const sorted = [...withBounds].sort((a, b) => a.y - b.y);
+  const yPositions = sorted.map((b) => b.y);
+  const rowClusters = clusterPositions(yPositions, config.rowTolerance);
+  if (rowClusters.length < config.minListItems) return null;
+  const rowGroups = /* @__PURE__ */ new Map();
+  for (const b of sorted) {
+    const row = assignToCluster(b.y, rowClusters, config.rowTolerance);
+    if (row >= 0) {
+      if (!rowGroups.has(row)) rowGroups.set(row, []);
+      rowGroups.get(row).push(b);
+    }
+  }
+  const items = [];
+  const fieldLabels = [];
+  let fieldLabelsInitialized = false;
+  for (const [, rowElements] of [...rowGroups.entries()].sort(([a], [b]) => a - b)) {
+    const sortedRow = [...rowElements].sort((a, b) => a.x - b.x);
+    const item = {};
+    for (let i = 0; i < sortedRow.length; i++) {
+      const label = `field_${i}`;
+      if (!fieldLabelsInitialized) fieldLabels.push(label);
+      item[label] = sortedRow[i].text;
+    }
+    fieldLabelsInitialized = true;
+    items.push(item);
+  }
+  if (items.length < config.minListItems) return null;
+  const fields = fieldLabels.map((label) => {
+    const values = items.map((item) => item[label]).filter(Boolean);
+    const types = values.map((v) => classifyDataType(v).type);
+    return { label, dataType: mode(types) ?? "text" };
+  });
+  return {
+    label: "List",
+    fields,
+    items
+  };
+}
+function extractStructuredData(elements, config = DEFAULT_TABLE_EXTRACTION_CONFIG) {
+  const tables = [];
+  const lists = [];
+  const table = detectTable(elements, config);
+  if (table) {
+    tables.push(table);
+  }
+  const listCandidates = elements.filter((el) => {
+    const role = el.role || el.type;
+    return ["listitem", "row", "option", "link", "button"].includes(role);
+  });
+  if (listCandidates.length >= config.minListItems) {
+    const list = detectList(listCandidates, config);
+    if (list) {
+      lists.push(list);
+    }
+  }
+  return { tables, lists };
+}
+function mode(arr) {
+  if (arr.length === 0) return void 0;
+  const counts = /* @__PURE__ */ new Map();
+  let best = arr[0];
+  let bestCount = 0;
+  for (const v of arr) {
+    const c = (counts.get(v) ?? 0) + 1;
+    counts.set(v, c);
+    if (c > bestCount) {
+      bestCount = c;
+      best = v;
+    }
+  }
+  return best;
+}
+
+// src/ai/format-analysis.ts
+var DEFAULT_FORMAT_ANALYSIS_CONFIG = {
+  lenientFormatting: true
+};
+function detectFormatPattern(value, dataType) {
+  const trimmed = value.trim();
+  switch (dataType) {
+    case "currency": {
+      const hasLeadingSymbol = /^[£$€¥₹]/.test(trimmed);
+      const hasTrailingSymbol = /[£$€¥₹]$/.test(trimmed);
+      const usesCommaThousands = /\d{1,3}(,\d{3})+/.test(trimmed);
+      const usesPeriodThousands = /\d{1,3}(\.\d{3})+,/.test(trimmed);
+      let pattern = hasLeadingSymbol ? "$" : "";
+      if (usesCommaThousands) pattern += "#,###";
+      else if (usesPeriodThousands) pattern += "#.###";
+      else pattern += "#";
+      if (/\.\d{2}$/.test(trimmed)) pattern += ".##";
+      else if (/,\d{2}$/.test(trimmed)) pattern += ",##";
+      if (hasTrailingSymbol) pattern += "$";
+      return pattern;
+    }
+    case "date": {
+      if (/^\d{4}-\d{2}-\d{2}/.test(trimmed)) return "YYYY-MM-DD";
+      if (/^\d{2}\/\d{2}\/\d{4}$/.test(trimmed)) return "MM/DD/YYYY";
+      if (/^\d{2}\.\d{2}\.\d{4}$/.test(trimmed)) return "DD.MM.YYYY";
+      if (/^\d{1,2}\/\d{1,2}\/\d{2}$/.test(trimmed)) return "M/D/YY";
+      if (/^\w{3,9}\s+\d{1,2},?\s+\d{4}$/.test(trimmed)) return "Month DD, YYYY";
+      return "date";
+    }
+    case "percentage":
+      return /\s%$/.test(trimmed) ? "#.## %" : "#.##%";
+    case "number": {
+      const hasCommas = /,/.test(trimmed);
+      const decimalPlaces = trimmed.includes(".") ? trimmed.split(".")[1]?.length || 0 : 0;
+      return (hasCommas ? "#,###" : "#") + (decimalPlaces > 0 ? "." + "#".repeat(decimalPlaces) : "");
+    }
+    case "phone": {
+      if (/^\(\d{3}\)\s?\d{3}-\d{4}$/.test(trimmed)) return "(###) ###-####";
+      if (/^\d{3}-\d{3}-\d{4}$/.test(trimmed)) return "###-###-####";
+      if (/^\+\d/.test(trimmed)) return "+# ###...";
+      return "phone";
+    }
+    default:
+      return dataType;
+  }
+}
+function analyzeFormat(elementId, label, rawValue) {
+  const { type: dataType } = classifyDataType(rawValue);
+  const pattern = detectFormatPattern(rawValue, dataType);
+  return {
+    elementId,
+    label,
+    dataType,
+    pattern,
+    example: rawValue.trim()
+  };
+}
+function analyzePageFormats(elements) {
+  const descriptors = [];
+  for (const el of elements) {
+    const rawValue = el.state?.value ?? el.state?.textContent ?? "";
+    if (!rawValue) continue;
+    const label = el.accessibleName || el.labelText || el.label || el.description || el.id;
+    descriptors.push(analyzeFormat(el.id, label, rawValue));
+  }
+  return descriptors;
+}
+function compareFormats(sourceFormats, targetFormats, config = DEFAULT_FORMAT_ANALYSIS_CONFIG) {
+  const mismatches = [];
+  const targetByLabel = /* @__PURE__ */ new Map();
+  for (const t of targetFormats) {
+    targetByLabel.set(t.label.toLowerCase(), t);
+  }
+  for (const source of sourceFormats) {
+    const target = targetByLabel.get(source.label.toLowerCase());
+    if (!target) continue;
+    if (source.dataType !== target.dataType) {
+      mismatches.push({
+        label: source.label,
+        sourceFormat: source,
+        targetFormat: target,
+        severity: "error",
+        description: `Data type mismatch: source is ${source.dataType}, target is ${target.dataType}`
+      });
+      continue;
+    }
+    if (source.pattern !== target.pattern) {
+      const severity = config.lenientFormatting ? "warning" : "error";
+      mismatches.push({
+        label: source.label,
+        sourceFormat: source,
+        targetFormat: target,
+        severity,
+        description: `Format differs: source uses "${source.pattern}", target uses "${target.pattern}"`
+      });
+    }
+  }
+  return mismatches;
+}
+
+// src/ai/cross-app-diff.ts
+var DEFAULT_CROSS_APP_DIFF_CONFIG = {
+  matchThreshold: 0.5,
+  accessibleNameWeight: 1,
+  textWeight: 0.95,
+  rolePositionWeight: 0.7
+};
+function getElementText(el) {
+  return el.accessibleName || el.labelText || el.label || el.state?.textContent || el.description || "";
+}
+function getRole(el) {
+  return (el.role || el.type || "").toLowerCase();
+}
+function getCenter(el) {
+  const rect = el.state?.rect;
+  if (!rect) return null;
+  return {
+    x: rect.x + rect.width / 2,
+    y: rect.y + rect.height / 2
+  };
+}
+function computeMatchScore(source, target, config) {
+  let bestScore = 0;
+  let bestStrategy = "none";
+  const srcName = (source.accessibleName || "").trim();
+  const tgtName = (target.accessibleName || "").trim();
+  if (srcName && tgtName && srcName.toLowerCase() === tgtName.toLowerCase()) {
+    return { score: config.accessibleNameWeight, strategy: "accessible-name-exact" };
+  }
+  const srcText = getElementText(source);
+  const tgtText = getElementText(target);
+  if (srcText && tgtText && srcText.toLowerCase() === tgtText.toLowerCase()) {
+    const score = config.textWeight;
+    if (score > bestScore) {
+      bestScore = score;
+      bestStrategy = "text-exact";
+    }
+  }
+  if (srcText && tgtText) {
+    const srcNorm = normalizeString(srcText);
+    const tgtNorm = normalizeString(tgtText);
+    const similarity = jaroWinklerSimilarity(srcNorm, tgtNorm);
+    const score = similarity * 0.85;
+    if (score > bestScore) {
+      bestScore = score;
+      bestStrategy = "text-fuzzy";
+    }
+  }
+  const srcRole = getRole(source);
+  const tgtRole = getRole(target);
+  if (srcRole && srcRole === tgtRole) {
+    const srcCenter = getCenter(source);
+    const tgtCenter = getCenter(target);
+    if (srcCenter && tgtCenter) {
+      const dx = Math.abs(srcCenter.x - tgtCenter.x) / 1920;
+      const dy = Math.abs(srcCenter.y - tgtCenter.y) / 1080;
+      const posSimilarity = 1 - Math.min(1, Math.sqrt(dx * dx + dy * dy));
+      const score = config.rolePositionWeight * posSimilarity;
+      if (score > bestScore) {
+        bestScore = score;
+        bestStrategy = "role-position";
+      }
+    }
+  }
+  const srcVal = source.state?.value ?? source.state?.textContent ?? "";
+  const tgtVal = target.state?.value ?? target.state?.textContent ?? "";
+  if (srcVal && tgtVal) {
+    const srcType = classifyDataType(srcVal).type;
+    const tgtType = classifyDataType(tgtVal).type;
+    const srcNorm = normalizeValue(srcVal, srcType);
+    const tgtNorm = normalizeValue(tgtVal, tgtType);
+    if (srcNorm === tgtNorm && srcNorm !== "") {
+      const score = 0.6;
+      if (score > bestScore) {
+        bestScore = score;
+        bestStrategy = "data-overlap";
+      }
+    }
+  }
+  return { score: bestScore, strategy: bestStrategy };
+}
+function matchElements(sourceElements, targetElements, config = DEFAULT_CROSS_APP_DIFF_CONFIG) {
+  const candidates = [];
+  for (let si = 0; si < sourceElements.length; si++) {
+    for (let ti = 0; ti < targetElements.length; ti++) {
+      const { score, strategy } = computeMatchScore(sourceElements[si], targetElements[ti], config);
+      if (score >= config.matchThreshold) {
+        candidates.push({ sourceIdx: si, targetIdx: ti, score, strategy });
+      }
+    }
+  }
+  candidates.sort((a, b) => b.score - a.score);
+  const usedSource = /* @__PURE__ */ new Set();
+  const usedTarget = /* @__PURE__ */ new Set();
+  const pairs = [];
+  for (const c of candidates) {
+    if (usedSource.has(c.sourceIdx) || usedTarget.has(c.targetIdx)) continue;
+    usedSource.add(c.sourceIdx);
+    usedTarget.add(c.targetIdx);
+    const src = sourceElements[c.sourceIdx];
+    const tgt = targetElements[c.targetIdx];
+    pairs.push({
+      sourceId: src.id,
+      targetId: tgt.id,
+      sourceLabel: getElementText(src) || src.id,
+      targetLabel: getElementText(tgt) || tgt.id,
+      confidence: Math.round(c.score * 100) / 100,
+      matchStrategy: c.strategy
+    });
+  }
+  return pairs;
+}
+function computeCrossAppDiff(sourceElements, targetElements, config = DEFAULT_CROSS_APP_DIFF_CONFIG) {
+  const matchedPairs = matchElements(sourceElements, targetElements, config);
+  const matchedSourceIds = new Set(matchedPairs.map((p) => p.sourceId));
+  const matchedTargetIds = new Set(matchedPairs.map((p) => p.targetId));
+  const unmatchedSourceIds = sourceElements.filter((e) => !matchedSourceIds.has(e.id)).map((e) => e.id);
+  const unmatchedTargetIds = targetElements.filter((e) => !matchedTargetIds.has(e.id)).map((e) => e.id);
+  const sourceData = extractPageData(sourceElements);
+  const targetData = extractPageData(targetElements);
+  const dataComparisons = [];
+  for (const pair of matchedPairs) {
+    const srcEntry = Object.values(sourceData.values).find((v) => v.elementId === pair.sourceId);
+    const tgtEntry = Object.values(targetData.values).find((v) => v.elementId === pair.targetId);
+    if (srcEntry && tgtEntry) {
+      dataComparisons.push({
+        label: pair.sourceLabel,
+        sourceValue: srcEntry.rawValue,
+        targetValue: tgtEntry.rawValue,
+        valuesMatch: srcEntry.normalizedValue === tgtEntry.normalizedValue,
+        formatsMatch: srcEntry.dataType === tgtEntry.dataType
+      });
+    }
+  }
+  const sourceFormats = analyzePageFormats(sourceElements);
+  const targetFormats = analyzePageFormats(targetElements);
+  const formatMismatches = compareFormats(sourceFormats, targetFormats);
+  return {
+    matchedPairs,
+    unmatchedSourceIds,
+    unmatchedTargetIds,
+    dataComparisons,
+    formatMismatches
+  };
+}
+
+// src/ai/action-parity.ts
+var DEFAULT_ACTION_PARITY_CONFIG = {
+  ignoreActions: []
+};
+function getActions(el, ignoreActions) {
+  const actions = el.actions || el.suggestedActions || [];
+  const ignoreSet = new Set(ignoreActions.map((a) => a.toLowerCase()));
+  return actions.map(
+    (a) => typeof a === "string" ? a : a.action || a.name || ""
+  ).filter((a) => a && !ignoreSet.has(a.toLowerCase()));
+}
+function analyzeActionParity(matchedPairs, sourceElements, targetElements, config = DEFAULT_ACTION_PARITY_CONFIG) {
+  const sourceById = new Map(sourceElements.map((e) => [e.id, e]));
+  const targetById = new Map(targetElements.map((e) => [e.id, e]));
+  const results = [];
+  for (const pair of matchedPairs) {
+    const src = sourceById.get(pair.sourceId);
+    const tgt = targetById.get(pair.targetId);
+    if (!src || !tgt) continue;
+    const sourceActions = getActions(src, config.ignoreActions);
+    const targetActions = getActions(tgt, config.ignoreActions);
+    const sourceSet = new Set(sourceActions.map((a) => a.toLowerCase()));
+    const targetSet = new Set(targetActions.map((a) => a.toLowerCase()));
+    const missingInTarget = sourceActions.filter((a) => !targetSet.has(a.toLowerCase()));
+    const missingInSource = targetActions.filter((a) => !sourceSet.has(a.toLowerCase()));
+    results.push({
+      pair,
+      sourceActions,
+      targetActions,
+      missingInTarget,
+      missingInSource
+    });
+  }
+  return results;
+}
+
+// src/ai/navigation-map.ts
+var DEFAULT_NAVIGATION_MAP_CONFIG = {
+  labelMatchThreshold: 0.8
+};
+function isNavigationElement(el) {
+  const role = (el.role || "").toLowerCase();
+  const type = (el.type || "").toLowerCase();
+  const semanticType = (el.semanticType || "").toLowerCase();
+  if (["link", "menuitem", "tab"].includes(role)) return true;
+  if (["link", "menuitem"].includes(type)) return true;
+  if (semanticType.includes("nav") || semanticType.includes("menu") || semanticType.includes("tab")) {
+    return true;
+  }
+  const context = (el.parentContext || "").toLowerCase();
+  if (context.includes("nav") || context.includes("menu") || context.includes("sidebar")) {
+    if (role === "button" || type === "button" || role === "link" || type === "link") {
+      return true;
+    }
+  }
+  return false;
+}
+function getNavLabel(el) {
+  return el.accessibleName || el.labelText || el.label || el.description || el.id;
+}
+function getHref(el) {
+  const state = el.state;
+  return state?.href || void 0;
+}
+function hrefsMatch(a, b) {
+  if (!a || !b) return false;
+  const normalize = (h) => h.replace(/^https?:\/\//, "").replace(/localhost:\d+/, "").replace(/\/+$/, "").toLowerCase();
+  return normalize(a) === normalize(b);
+}
+function buildNavigationMap(sourceElements, targetElements, config = DEFAULT_NAVIGATION_MAP_CONFIG) {
+  const sourceNav = sourceElements.filter(isNavigationElement);
+  const targetNav = targetElements.filter(isNavigationElement);
+  const pairs = [];
+  const matchedTargetIds = /* @__PURE__ */ new Set();
+  for (const src of sourceNav) {
+    const srcLabel = getNavLabel(src);
+    const srcNorm = normalizeString(srcLabel);
+    let bestTarget = null;
+    let bestScore = 0;
+    for (const tgt of targetNav) {
+      if (matchedTargetIds.has(tgt.id)) continue;
+      const tgtLabel = getNavLabel(tgt);
+      const tgtNorm = normalizeString(tgtLabel);
+      if (srcNorm === tgtNorm) {
+        bestTarget = tgt;
+        bestScore = 1;
+        break;
+      }
+      const similarity = jaroWinklerSimilarity(srcNorm, tgtNorm);
+      if (similarity > bestScore && similarity >= config.labelMatchThreshold) {
+        bestScore = similarity;
+        bestTarget = tgt;
+      }
+    }
+    if (bestTarget) {
+      matchedTargetIds.add(bestTarget.id);
+      const srcHref = getHref(src);
+      const tgtHref = getHref(bestTarget);
+      pairs.push({
+        sourceId: src.id,
+        targetId: bestTarget.id,
+        label: srcLabel,
+        sourceHref: srcHref,
+        targetHref: tgtHref,
+        destinationMatch: hrefsMatch(srcHref, tgtHref)
+      });
+    }
+  }
+  const sourceOnly = sourceNav.filter((s) => !pairs.some((p) => p.sourceId === s.id)).map((s) => s.id);
+  const targetOnly = targetNav.filter((t) => !matchedTargetIds.has(t.id)).map((t) => t.id);
+  return { pairs, sourceOnly, targetOnly };
+}
+
+// src/ai/component-comparison.ts
+var DEFAULT_COMPONENT_COMPARISON_CONFIG = {
+  nameMatchThreshold: 0.75
+};
+function computeComponentMatchScore(source, target) {
+  if (source.name.toLowerCase() === target.name.toLowerCase()) return 1;
+  let score = 0;
+  if (source.type === target.type) {
+    score += 0.3;
+  }
+  const nameSimilarity = jaroWinklerSimilarity(
+    normalizeString(source.name),
+    normalizeString(target.name)
+  );
+  score += nameSimilarity * 0.7;
+  return score;
+}
+function compareComponents(sourceComponents, targetComponents, config = DEFAULT_COMPONENT_COMPARISON_CONFIG) {
+  const candidates = [];
+  for (let si = 0; si < sourceComponents.length; si++) {
+    for (let ti = 0; ti < targetComponents.length; ti++) {
+      const score = computeComponentMatchScore(sourceComponents[si], targetComponents[ti]);
+      if (score >= config.nameMatchThreshold) {
+        candidates.push({ sourceIdx: si, targetIdx: ti, score });
+      }
+    }
+  }
+  candidates.sort((a, b) => b.score - a.score);
+  const usedSource = /* @__PURE__ */ new Set();
+  const usedTarget = /* @__PURE__ */ new Set();
+  const matches = [];
+  for (const c of candidates) {
+    if (usedSource.has(c.sourceIdx) || usedTarget.has(c.targetIdx)) continue;
+    usedSource.add(c.sourceIdx);
+    usedTarget.add(c.targetIdx);
+    const src = sourceComponents[c.sourceIdx];
+    const tgt = targetComponents[c.targetIdx];
+    const srcKeys = new Set(src.stateKeys);
+    const tgtKeys = new Set(tgt.stateKeys);
+    const missingKeys = src.stateKeys.filter((k) => !tgtKeys.has(k));
+    const extraKeys = tgt.stateKeys.filter((k) => !srcKeys.has(k));
+    const srcActions = new Set(src.actions.map((a) => a.toLowerCase()));
+    const tgtActions = new Set(tgt.actions.map((a) => a.toLowerCase()));
+    const missingActions = src.actions.filter((a) => !tgtActions.has(a.toLowerCase()));
+    const extraActions = tgt.actions.filter((a) => !srcActions.has(a.toLowerCase()));
+    matches.push({
+      source: src,
+      target: tgt,
+      confidence: Math.round(c.score * 100) / 100,
+      stateKeyDiff: { missing: missingKeys, extra: extraKeys },
+      actionDiff: { missing: missingActions, extra: extraActions }
+    });
+  }
+  const sourceOnly = sourceComponents.filter((_, i) => !usedSource.has(i));
+  const targetOnly = targetComponents.filter((_, i) => !usedTarget.has(i));
+  return { matches, sourceOnly, targetOnly };
+}
+
+// src/ai/layout-comparison.ts
+var DEFAULT_LAYOUT_COMPARISON_CONFIG = {
+  gridTolerance: 20
+};
+function getRect(el) {
+  const rect = el.state?.rect;
+  if (!rect || !rect.width) return null;
+  return { x: rect.x, y: rect.y, width: rect.width, height: rect.height };
+}
+function clusterValues(values, tolerance) {
+  if (values.length === 0) return [];
+  const sorted = [...values].sort((a, b) => a - b);
+  const clusters = [sorted[0]];
+  for (let i = 1; i < sorted.length; i++) {
+    if (sorted[i] - clusters[clusters.length - 1] > tolerance) {
+      clusters.push(sorted[i]);
+    }
+  }
+  return clusters;
+}
+function detectGridStructure(elements, config = DEFAULT_LAYOUT_COMPARISON_CONFIG) {
+  const rects = elements.map(getRect).filter((r) => r !== null);
+  const xPositions = rects.map((r) => r.x);
+  const yPositions = rects.map((r) => r.y);
+  const columns = clusterValues(xPositions, config.gridTolerance);
+  const rows = clusterValues(yPositions, config.gridTolerance);
+  return {
+    columns,
+    rows,
+    columnCount: columns.length,
+    rowCount: rows.length
+  };
+}
+function computeMaxDepth(elements) {
+  let maxDepth = 0;
+  for (const el of elements) {
+    const context = el.parentContext || "";
+    const depth = context ? context.split(">").length : 1;
+    maxDepth = Math.max(maxDepth, depth);
+  }
+  return maxDepth;
+}
+function compareLayouts(sourceElements, targetElements, sourceRegions, targetRegions, config = DEFAULT_LAYOUT_COMPARISON_CONFIG) {
+  const sourceGrid = detectGridStructure(sourceElements, config);
+  const targetGrid = detectGridStructure(targetElements, config);
+  const gridDiff = {
+    sourceGrid,
+    targetGrid,
+    columnDiff: sourceGrid.columnCount - targetGrid.columnCount,
+    rowDiff: sourceGrid.rowCount - targetGrid.rowCount
+  };
+  const sourceDepth = computeMaxDepth(sourceElements);
+  const targetDepth = computeMaxDepth(targetElements);
+  const hierarchyDiff = {
+    sourceDepth,
+    targetDepth,
+    depthDiff: sourceDepth - targetDepth
+  };
+  const sourceRegionCount = sourceRegions?.regions.length || 1;
+  const targetRegionCount = targetRegions?.regions.length || 1;
+  const sourceDensity = sourceElements.length / sourceRegionCount;
+  const targetDensity = targetElements.length / targetRegionCount;
+  const density = {
+    sourceDensity: Math.round(sourceDensity * 100) / 100,
+    targetDensity: Math.round(targetDensity * 100) / 100,
+    ratio: targetDensity > 0 ? Math.round(sourceDensity / targetDensity * 100) / 100 : 0
+  };
+  const gridSimilarity = sourceGrid.columnCount === 0 && targetGrid.columnCount === 0 ? 1 : 1 - Math.abs(gridDiff.columnDiff) / Math.max(sourceGrid.columnCount, targetGrid.columnCount, 1);
+  const hierarchySimilarity = sourceDepth === 0 && targetDepth === 0 ? 1 : 1 - Math.abs(hierarchyDiff.depthDiff) / Math.max(sourceDepth, targetDepth, 1);
+  const densitySimilarity = density.ratio > 0 ? Math.min(density.ratio, 1 / density.ratio) : 0;
+  const similarity = Math.round((gridSimilarity * 0.4 + hierarchySimilarity * 0.3 + densitySimilarity * 0.3) * 100) / 100;
+  return {
+    gridDiff,
+    hierarchyDiff,
+    density,
+    similarity
+  };
+}
+
+// src/ai/content-comparison.ts
+var DEFAULT_CONTENT_COMPARISON_CONFIG = {
+  labelMatchThreshold: 0.8,
+  headingMatchThreshold: 0.75,
+  maxCellDifferences: 50
+};
+function getElementText2(el) {
+  return (el.accessibleName || el.labelText || el.label || el.state?.textContent || el.description || "").trim();
+}
+function getContentRole(el) {
+  if (el.contentMetadata?.contentRole) {
+    return el.contentMetadata.contentRole;
+  }
+  const t = (el.type || "").toLowerCase();
+  if (t === "heading" || t.startsWith("h") && /^h[1-6]$/.test(t)) return "heading";
+  if (t === "metric-value" || t === "metric") return "metric";
+  if (t === "status-message" || t === "status") return "status";
+  if (t === "label") return "label";
+  if (t === "badge") return "badge";
+  if (t === "table-cell") return "table-cell";
+  if (t === "table-header") return "table-header";
+  if (t === "caption") return "caption";
+  return null;
+}
+function getHeadingLevel(el) {
+  if (el.contentMetadata?.headingLevel) {
+    return el.contentMetadata.headingLevel;
+  }
+  const tag = (el.tagName || el.type || "").toLowerCase();
+  const match = /^h([1-6])$/.exec(tag);
+  if (match) return parseInt(match[1], 10);
+  return void 0;
+}
+function isContentElement2(el) {
+  if (el.category === "content") return true;
+  if (el.contentMetadata) return true;
+  const role = getContentRole(el);
+  return role !== null;
+}
+function normalizeText(text) {
+  return normalizeString(text, { caseSensitive: false, ignoreWhitespace: true });
+}
+function parseMetricText(el) {
+  const text = getElementText2(el);
+  const colonMatch = text.match(/^(.+?):\s*(.+)$/);
+  if (colonMatch) {
+    return { label: colonMatch[1].trim(), value: colonMatch[2].trim() };
+  }
+  const dashMatch = text.match(/^(.+?)\s*[-]\s*(.+)$/);
+  if (dashMatch) {
+    return { label: dashMatch[1].trim(), value: dashMatch[2].trim() };
+  }
+  const elLabel = el.accessibleName || el.labelText || el.label || el.id;
+  return { label: elLabel, value: text };
+}
+function filterHeadings(elements) {
+  return elements.filter((el) => getContentRole(el) === "heading");
+}
+function filterMetrics(elements) {
+  return elements.filter((el) => getContentRole(el) === "metric");
+}
+function filterStatuses(elements) {
+  return elements.filter((el) => {
+    const role = getContentRole(el);
+    return role === "status" || role === "badge";
+  });
+}
+function filterLabels(elements) {
+  return elements.filter((el) => {
+    const role = getContentRole(el);
+    return role === "label" || role === "caption";
+  });
+}
+function matchTexts(sourceTexts, targetTexts, threshold) {
+  const candidates = [];
+  for (let si = 0; si < sourceTexts.length; si++) {
+    const sNorm = normalizeText(sourceTexts[si]);
+    if (!sNorm) continue;
+    for (let ti = 0; ti < targetTexts.length; ti++) {
+      const tNorm = normalizeText(targetTexts[ti]);
+      if (!tNorm) continue;
+      const score = sNorm === tNorm ? 1 : jaroWinklerSimilarity(sNorm, tNorm);
+      if (score >= threshold) {
+        candidates.push({ sourceIdx: si, targetIdx: ti, score });
+      }
+    }
+  }
+  candidates.sort((a, b) => b.score - a.score);
+  const usedSource = /* @__PURE__ */ new Set();
+  const usedTarget = /* @__PURE__ */ new Set();
+  const matched = [];
+  for (const c of candidates) {
+    if (usedSource.has(c.sourceIdx) || usedTarget.has(c.targetIdx)) continue;
+    usedSource.add(c.sourceIdx);
+    usedTarget.add(c.targetIdx);
+    matched.push(c);
+  }
+  const unmatchedSource = sourceTexts.map((_, i) => i).filter((i) => !usedSource.has(i));
+  const unmatchedTarget = targetTexts.map((_, i) => i).filter((i) => !usedTarget.has(i));
+  return { matched, unmatchedSource, unmatchedTarget };
+}
+function compareHeadings(sourceElements, targetElements, config) {
+  const srcHeadings = filterHeadings(sourceElements);
+  const tgtHeadings = filterHeadings(targetElements);
+  const srcTexts = srcHeadings.map(getElementText2);
+  const tgtTexts = tgtHeadings.map(getElementText2);
+  const { matched, unmatchedSource, unmatchedTarget } = matchTexts(
+    srcTexts,
+    tgtTexts,
+    config.headingMatchThreshold
+  );
+  const headingMatched = [];
+  const headingChanged = [];
+  for (const m of matched) {
+    const srcText = srcTexts[m.sourceIdx];
+    const tgtText = tgtTexts[m.targetIdx];
+    const srcLevel = getHeadingLevel(srcHeadings[m.sourceIdx]);
+    const tgtLevel = getHeadingLevel(tgtHeadings[m.targetIdx]);
+    if (normalizeText(srcText) === normalizeText(tgtText)) {
+      headingMatched.push({
+        source: srcText,
+        target: tgtText,
+        level: srcLevel
+      });
+    } else {
+      headingChanged.push({
+        source: srcText,
+        target: tgtText,
+        level: srcLevel ?? tgtLevel
+      });
+    }
+  }
+  return {
+    matched: headingMatched,
+    sourceOnly: unmatchedSource.map((i) => srcTexts[i]),
+    targetOnly: unmatchedTarget.map((i) => tgtTexts[i]),
+    changed: headingChanged
+  };
+}
+function compareMetrics(sourceElements, targetElements, config) {
+  const srcMetrics = filterMetrics(sourceElements);
+  const tgtMetrics = filterMetrics(targetElements);
+  const srcParsed = srcMetrics.map(parseMetricText);
+  const tgtParsed = tgtMetrics.map(parseMetricText);
+  const srcLabels = srcParsed.map((p) => p.label);
+  const tgtLabels = tgtParsed.map((p) => p.label);
+  const { matched, unmatchedSource, unmatchedTarget } = matchTexts(
+    srcLabels,
+    tgtLabels,
+    config.labelMatchThreshold
+  );
+  const metricMatched = [];
+  const metricChanged = [];
+  for (const m of matched) {
+    const src = srcParsed[m.sourceIdx];
+    const tgt = tgtParsed[m.targetIdx];
+    if (normalizeText(src.value) === normalizeText(tgt.value)) {
+      metricMatched.push({
+        label: src.label,
+        sourceValue: src.value,
+        targetValue: tgt.value
+      });
+    } else {
+      metricChanged.push({
+        label: src.label,
+        sourceValue: src.value,
+        targetValue: tgt.value
+      });
+    }
+  }
+  return {
+    matched: metricMatched,
+    changed: metricChanged,
+    sourceOnly: unmatchedSource.map((i) => srcParsed[i].label),
+    targetOnly: unmatchedTarget.map((i) => tgtParsed[i].label)
+  };
+}
+function compareStatuses(sourceElements, targetElements, config) {
+  const srcStatuses = filterStatuses(sourceElements);
+  const tgtStatuses = filterStatuses(targetElements);
+  const srcParsed = srcStatuses.map(parseMetricText);
+  const tgtParsed = tgtStatuses.map(parseMetricText);
+  const srcLabels = srcParsed.map((p) => p.label);
+  const tgtLabels = tgtParsed.map((p) => p.label);
+  const { matched } = matchTexts(srcLabels, tgtLabels, config.labelMatchThreshold);
+  const statusMatched = [];
+  const statusChanged = [];
+  for (const m of matched) {
+    const src = srcParsed[m.sourceIdx];
+    const tgt = tgtParsed[m.targetIdx];
+    if (normalizeText(src.value) === normalizeText(tgt.value)) {
+      statusMatched.push({
+        label: src.label,
+        sourceStatus: src.value,
+        targetStatus: tgt.value
+      });
+    } else {
+      statusChanged.push({
+        label: src.label,
+        sourceStatus: src.value,
+        targetStatus: tgt.value
+      });
+    }
+  }
+  return {
+    matched: statusMatched,
+    changed: statusChanged
+  };
+}
+function compareLabels(sourceElements, targetElements, config) {
+  const srcLabels = filterLabels(sourceElements);
+  const tgtLabels = filterLabels(targetElements);
+  const srcTexts = srcLabels.map(getElementText2);
+  const tgtTexts = tgtLabels.map(getElementText2);
+  const { matched, unmatchedSource, unmatchedTarget } = matchTexts(
+    srcTexts,
+    tgtTexts,
+    config.labelMatchThreshold
+  );
+  return {
+    matched: matched.map((m) => srcTexts[m.sourceIdx]),
+    sourceOnly: unmatchedSource.map((i) => srcTexts[i]),
+    targetOnly: unmatchedTarget.map((i) => tgtTexts[i])
+  };
+}
+function compareTables(sourceElements, targetElements, config) {
+  const srcData = extractStructuredData(sourceElements);
+  const tgtData = extractStructuredData(targetElements);
+  const srcTables = srcData.tables;
+  const tgtTables = tgtData.tables;
+  if (srcTables.length === 0 || tgtTables.length === 0) {
+    return [];
+  }
+  const srcTableLabels = srcTables.map((t) => t.label || "");
+  const tgtTableLabels = tgtTables.map((t) => t.label || "");
+  const { matched } = matchTexts(srcTableLabels, tgtTableLabels, config.labelMatchThreshold);
+  const tablePairs = [];
+  if (matched.length > 0) {
+    for (const m of matched) {
+      tablePairs.push({ srcIdx: m.sourceIdx, tgtIdx: m.targetIdx });
+    }
+  } else if (srcTables.length === 1 && tgtTables.length === 1) {
+    tablePairs.push({ srcIdx: 0, tgtIdx: 0 });
+  }
+  const comparisons = [];
+  for (const pair of tablePairs) {
+    const srcTable = srcTables[pair.srcIdx];
+    const tgtTable = tgtTables[pair.tgtIdx];
+    const srcHeaders = srcTable.columns.map((c) => c.header);
+    const tgtHeaders = tgtTable.columns.map((c) => c.header);
+    const srcHeaderSet = new Set(srcHeaders.map(normalizeText));
+    const tgtHeaderSet = new Set(tgtHeaders.map(normalizeText));
+    const sourceOnlyColumns = srcHeaders.filter((h) => !tgtHeaderSet.has(normalizeText(h)));
+    const targetOnlyColumns = tgtHeaders.filter((h) => !srcHeaderSet.has(normalizeText(h)));
+    const columnsMatch = sourceOnlyColumns.length === 0 && targetOnlyColumns.length === 0;
+    const cellDifferences = [];
+    const commonHeaders = srcHeaders.filter((h) => tgtHeaderSet.has(normalizeText(h)));
+    const minRows = Math.min(srcTable.rows.length, tgtTable.rows.length);
+    for (let row = 0; row < minRows; row++) {
+      if (cellDifferences.length >= config.maxCellDifferences) break;
+      for (const header of commonHeaders) {
+        const srcColIdx = srcHeaders.indexOf(header);
+        const tgtColIdx = tgtHeaders.findIndex((h) => normalizeText(h) === normalizeText(header));
+        if (srcColIdx < 0 || tgtColIdx < 0) continue;
+        const srcValue = srcTable.rows[row]?.[srcColIdx] ?? "";
+        const tgtValue = tgtTable.rows[row]?.[tgtColIdx] ?? "";
+        if (normalizeText(srcValue) !== normalizeText(tgtValue)) {
+          cellDifferences.push({
+            row,
+            column: header,
+            sourceValue: srcValue,
+            targetValue: tgtValue
+          });
+        }
+      }
+    }
+    comparisons.push({
+      sourceLabel: srcTable.label,
+      targetLabel: tgtTable.label,
+      columnsMatch,
+      sourceOnlyColumns,
+      targetOnlyColumns,
+      sourceRowCount: srcTable.rows.length,
+      targetRowCount: tgtTable.rows.length,
+      cellDifferences
+    });
+  }
+  return comparisons;
+}
+function compareHeadingHierarchy(sourceElements, targetElements) {
+  const srcHeadings = filterHeadings(sourceElements);
+  const tgtHeadings = filterHeadings(targetElements);
+  const srcByLevel = /* @__PURE__ */ new Map();
+  const tgtByLevel = /* @__PURE__ */ new Map();
+  for (const el of srcHeadings) {
+    const level = getHeadingLevel(el) ?? 0;
+    srcByLevel.set(level, (srcByLevel.get(level) ?? 0) + 1);
+  }
+  for (const el of tgtHeadings) {
+    const level = getHeadingLevel(el) ?? 0;
+    tgtByLevel.set(level, (tgtByLevel.get(level) ?? 0) + 1);
+  }
+  const allLevels = /* @__PURE__ */ new Set([...srcByLevel.keys(), ...tgtByLevel.keys()]);
+  const result = [];
+  for (const level of [...allLevels].sort()) {
+    result.push({
+      level,
+      sourceCount: srcByLevel.get(level) ?? 0,
+      targetCount: tgtByLevel.get(level) ?? 0
+    });
+  }
+  return result;
+}
+function compareContent(sourceElements, targetElements, config = DEFAULT_CONTENT_COMPARISON_CONFIG) {
+  const srcContent = sourceElements.filter(isContentElement2);
+  const tgtContent = targetElements.filter(isContentElement2);
+  const headings = compareHeadings(srcContent, tgtContent, config);
+  const metrics = compareMetrics(srcContent, tgtContent, config);
+  const statuses = compareStatuses(srcContent, tgtContent, config);
+  const labels = compareLabels(srcContent, tgtContent, config);
+  const tables = compareTables(sourceElements, targetElements, config);
+  const headingHierarchy = compareHeadingHierarchy(srcContent, tgtContent);
+  const contentParity = calculateContentParity(headings, metrics, statuses, labels, tables);
+  return {
+    headings,
+    metrics,
+    statuses,
+    labels,
+    tables,
+    headingHierarchy,
+    contentParity
+  };
+}
+function calculateContentParity(headings, metrics, statuses, labels, tables) {
+  const scores = [];
+  const totalHeadings = headings.matched.length + headings.changed.length + headings.sourceOnly.length + headings.targetOnly.length;
+  if (totalHeadings > 0) {
+    scores.push(headings.matched.length / totalHeadings);
+  }
+  const totalMetrics = metrics.matched.length + metrics.changed.length + metrics.sourceOnly.length + metrics.targetOnly.length;
+  if (totalMetrics > 0) {
+    const metricScore = (metrics.matched.length + metrics.changed.length * 0.5) / totalMetrics;
+    scores.push(metricScore);
+  }
+  const totalStatuses = statuses.matched.length + statuses.changed.length;
+  if (totalStatuses > 0) {
+    scores.push(statuses.matched.length / totalStatuses);
+  }
+  const totalLabels = labels.matched.length + labels.sourceOnly.length + labels.targetOnly.length;
+  if (totalLabels > 0) {
+    scores.push(labels.matched.length / totalLabels);
+  }
+  if (tables.length > 0) {
+    let tableScore = 0;
+    for (const table of tables) {
+      let tScore = table.columnsMatch ? 0.5 : 0;
+      if (table.sourceRowCount > 0) {
+        const rowRatio = Math.min(
+          table.targetRowCount / table.sourceRowCount,
+          table.sourceRowCount / table.targetRowCount
+        );
+        tScore += rowRatio * 0.3;
+      } else {
+        tScore += 0.3;
+      }
+      const totalCells = Math.max(table.sourceRowCount, 1) * Math.max(
+        table.sourceOnlyColumns.length + table.targetOnlyColumns.length + (table.columnsMatch ? 1 : 0),
+        1
+      );
+      const diffRatio = totalCells > 0 ? 1 - Math.min(table.cellDifferences.length / totalCells, 1) : 1;
+      tScore += diffRatio * 0.2;
+      tableScore += tScore;
+    }
+    scores.push(tableScore / tables.length);
+  }
+  if (scores.length === 0) return 1;
+  return Math.round(scores.reduce((a, b) => a + b, 0) / scores.length * 100) / 100;
+}
+
+// src/ai/comparison-report.ts
+var DEFAULT_COMPARISON_REPORT_CONFIG = {
+  includeComponents: false
+};
+function generateComparisonReport(source, target, options) {
+  const startTime = Date.now();
+  const config = { ...DEFAULT_COMPARISON_REPORT_CONFIG, ...options?.config };
+  const srcElements = source.elements;
+  const tgtElements = target.elements;
+  const diff = computeCrossAppDiff(srcElements, tgtElements);
+  const navigation = buildNavigationMap(srcElements, tgtElements);
+  const sourceRegions = segmentPageRegions(srcElements);
+  const targetRegions = segmentPageRegions(tgtElements);
+  const layout = compareLayouts(srcElements, tgtElements, sourceRegions, targetRegions);
+  const actionParityResults = analyzeActionParity(diff.matchedPairs, srcElements, tgtElements);
+  const componentComparison = config.includeComponents && options?.sourceComponents && options?.targetComponents ? compareComponents(options.sourceComponents, options.targetComponents) : null;
+  const contentComparison = compareContent(srcElements, tgtElements);
+  const sourceData = extractPageData(srcElements);
+  extractPageData(tgtElements);
+  const sourceFieldCount = Object.keys(sourceData.values).length;
+  const matchedDataCount = diff.dataComparisons.length;
+  const dataCompleteness = sourceFieldCount > 0 ? Math.round(matchedDataCount / sourceFieldCount * 100) / 100 : 1;
+  const formatMatchCount = diff.dataComparisons.filter((c) => c.formatsMatch).length;
+  const formatAlignment = matchedDataCount > 0 ? Math.round(formatMatchCount / matchedDataCount * 100) / 100 : 1;
+  const presentationAlignment = layout.similarity;
+  const totalNavItems = navigation.pairs.length + navigation.sourceOnly.length;
+  const navigationParity = totalNavItems > 0 ? Math.round(navigation.pairs.length / totalNavItems * 100) / 100 : 1;
+  const totalActionChecks = actionParityResults.length;
+  const fullParityCount = actionParityResults.filter((r) => r.missingInTarget.length === 0).length;
+  const actionParity = totalActionChecks > 0 ? Math.round(fullParityCount / totalActionChecks * 100) / 100 : 1;
+  const contentParity = contentComparison.contentParity;
+  const overallScore = Math.round(
+    (dataCompleteness * 0.2 + formatAlignment * 0.1 + presentationAlignment * 0.15 + navigationParity * 0.15 + actionParity * 0.15 + contentParity * 0.25) * 100
+  ) / 100;
+  const issues = [];
+  for (const srcId of diff.unmatchedSourceIds) {
+    const srcVal = Object.values(sourceData.values).find((v) => v.elementId === srcId);
+    if (srcVal) {
+      issues.push({
+        severity: "warning",
+        category: "missing-data",
+        description: `Data field "${srcVal.label}" (${srcVal.dataType}) exists in source but has no match in target`,
+        sourceElementId: srcId
+      });
+    }
+  }
+  for (const comp of diff.dataComparisons) {
+    if (!comp.valuesMatch) {
+      issues.push({
+        severity: "error",
+        category: "value-mismatch",
+        description: `Value mismatch for "${comp.label}": source="${comp.sourceValue}", target="${comp.targetValue}"`
+      });
+    }
+  }
+  for (const fm of diff.formatMismatches) {
+    issues.push({
+      severity: fm.severity,
+      category: "format-mismatch",
+      description: fm.description
+    });
+  }
+  for (const ap of actionParityResults) {
+    for (const action of ap.missingInTarget) {
+      issues.push({
+        severity: "warning",
+        category: "missing-action",
+        description: `Action "${action}" available on source element "${ap.pair.sourceLabel}" is missing in target`,
+        sourceElementId: ap.pair.sourceId,
+        targetElementId: ap.pair.targetId
+      });
+    }
+  }
+  for (const srcId of navigation.sourceOnly) {
+    issues.push({
+      severity: "warning",
+      category: "navigation-gap",
+      description: `Navigation item "${srcId}" in source has no match in target`,
+      sourceElementId: srcId
+    });
+  }
+  if (layout.similarity < 0.5) {
+    issues.push({
+      severity: "warning",
+      category: "layout-difference",
+      description: `Layout similarity is low (${layout.similarity}). Grid: ${layout.gridDiff.sourceGrid.columnCount} cols vs ${layout.gridDiff.targetGrid.columnCount} cols`
+    });
+  }
+  if (componentComparison) {
+    for (const src of componentComparison.sourceOnly) {
+      issues.push({
+        severity: "info",
+        category: "component-mismatch",
+        description: `Component "${src.name}" (${src.type}) exists in source but not target`
+      });
+    }
+    for (const match of componentComparison.matches) {
+      if (match.stateKeyDiff.missing.length > 0) {
+        issues.push({
+          severity: "warning",
+          category: "component-mismatch",
+          description: `Component "${match.source.name}": state keys missing in target: ${match.stateKeyDiff.missing.join(", ")}`
+        });
+      }
+    }
+  }
+  for (const heading of contentComparison.headings.sourceOnly) {
+    issues.push({
+      severity: "warning",
+      category: "content-difference",
+      description: `Heading "${heading}" exists in source but not in target`
+    });
+  }
+  for (const heading of contentComparison.headings.targetOnly) {
+    issues.push({
+      severity: "info",
+      category: "content-difference",
+      description: `Heading "${heading}" exists in target but not in source`
+    });
+  }
+  for (const change of contentComparison.headings.changed) {
+    issues.push({
+      severity: "warning",
+      category: "content-difference",
+      description: `Heading changed: "${change.source}" -> "${change.target}"`
+    });
+  }
+  for (const change of contentComparison.metrics.changed) {
+    issues.push({
+      severity: "warning",
+      category: "content-difference",
+      description: `Metric "${change.label}" value differs: "${change.sourceValue}" vs "${change.targetValue}"`
+    });
+  }
+  for (const label of contentComparison.metrics.sourceOnly) {
+    issues.push({
+      severity: "warning",
+      category: "content-difference",
+      description: `Metric "${label}" exists in source but not in target`
+    });
+  }
+  for (const change of contentComparison.statuses.changed) {
+    issues.push({
+      severity: "warning",
+      category: "content-difference",
+      description: `Status "${change.label}" differs: "${change.sourceStatus}" vs "${change.targetStatus}"`
+    });
+  }
+  for (const table of contentComparison.tables) {
+    if (!table.columnsMatch) {
+      issues.push({
+        severity: "warning",
+        category: "content-difference",
+        description: `Table "${table.sourceLabel}" column mismatch: source-only=[${table.sourceOnlyColumns.join(", ")}], target-only=[${table.targetOnlyColumns.join(", ")}]`
+      });
+    }
+    if (table.sourceRowCount !== table.targetRowCount) {
+      issues.push({
+        severity: "info",
+        category: "content-difference",
+        description: `Table "${table.sourceLabel}" row count differs: ${table.sourceRowCount} vs ${table.targetRowCount}`
+      });
+    }
+    if (table.cellDifferences.length > 0) {
+      issues.push({
+        severity: "warning",
+        category: "content-difference",
+        description: `Table "${table.sourceLabel}" has ${table.cellDifferences.length} cell value difference(s)`
+      });
+    }
+  }
+  const severityOrder = { error: 0, warning: 1, info: 2 };
+  issues.sort((a, b) => severityOrder[a.severity] - severityOrder[b.severity]);
+  const errorCount = issues.filter((i) => i.severity === "error").length;
+  const warningCount = issues.filter((i) => i.severity === "warning").length;
+  const infoCount = issues.filter((i) => i.severity === "info").length;
+  const summaryLines = [
+    `Cross-app comparison: ${source.page.url} vs ${target.page.url}`,
+    `Overall score: ${(overallScore * 100).toFixed(0)}%`,
+    `Matched elements: ${diff.matchedPairs.length}`,
+    `Unmatched: ${diff.unmatchedSourceIds.length} source, ${diff.unmatchedTargetIds.length} target`,
+    `Navigation: ${navigation.pairs.length} matched, ${navigation.sourceOnly.length} source-only, ${navigation.targetOnly.length} target-only`
+  ];
+  if (componentComparison) {
+    summaryLines.push(
+      `Components: ${componentComparison.matches.length} matched, ${componentComparison.sourceOnly.length} source-only, ${componentComparison.targetOnly.length} target-only`
+    );
+  }
+  const hMatched = contentComparison.headings.matched.length;
+  const hChanged = contentComparison.headings.changed.length;
+  const hSrcOnly = contentComparison.headings.sourceOnly.length;
+  const hTgtOnly = contentComparison.headings.targetOnly.length;
+  const mMatched = contentComparison.metrics.matched.length;
+  const mChanged = contentComparison.metrics.changed.length;
+  const sMatched = contentComparison.statuses.matched.length;
+  const sChanged = contentComparison.statuses.changed.length;
+  const totalContent = hMatched + hChanged + hSrcOnly + hTgtOnly + mMatched + mChanged + sMatched + sChanged;
+  if (totalContent > 0) {
+    summaryLines.push(
+      `Content: headings=${hMatched} matched/${hChanged} changed/${hSrcOnly + hTgtOnly} unmatched, metrics=${mMatched} matched/${mChanged} changed, statuses=${sMatched} matched/${sChanged} changed, parity=${(contentParity * 100).toFixed(0)}%`
+    );
+  }
+  summaryLines.push(`Issues: ${errorCount} errors, ${warningCount} warnings, ${infoCount} info`);
+  const summary = summaryLines.join("\n");
+  const report = {
+    sourceUrl: source.page.url,
+    targetUrl: target.page.url,
+    timestamp: Date.now(),
+    durationMs: Date.now() - startTime,
+    scores: {
+      dataCompleteness,
+      formatAlignment,
+      presentationAlignment,
+      navigationParity,
+      actionParity,
+      overallScore
+    },
+    diff,
+    navigation,
+    layout,
+    contentComparison,
+    issues,
+    summary
+  };
+  if (componentComparison) {
+    report.components = componentComparison;
+  }
+  return report;
+}
+
+// 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",
@@ -3649,6 +5967,9 @@ function createHandlers(registry, actionExecutor, config = {}) {
   const assertionExecutor = new AssertionExecutor();
   const snapshotManager = new SemanticSnapshotManager();
   const diffManager = new SemanticDiffManager();
+  const intentRegistry = /* @__PURE__ */ new Map();
+  const consoleCapture = config.consoleCapture ?? null;
+  const annotationStore = config.annotationStore ?? getGlobalAnnotationStore();
   function refreshElements() {
     const elements = registry.getAllElements();
     searchEngine.updateElements(elements);
@@ -3715,10 +6036,14 @@ function createHandlers(registry, actionExecutor, config = {}) {
       try {
         const element = registry.getElement(id);
         if (!element) {
-          const failureDetails = createFailureDetails("ELEMENT_NOT_FOUND", `Element not found: ${id}`, {
-            elementId: id,
-            selectorsTried: [id]
-          });
+          const failureDetails = createFailureDetails(
+            "ELEMENT_NOT_FOUND",
+            `Element not found: ${id}`,
+            {
+              elementId: id,
+              selectorsTried: [id]
+            }
+          );
           return {
             success: false,
             error: `Element not found: ${id}`,
@@ -3748,11 +6073,15 @@ function createHandlers(registry, actionExecutor, config = {}) {
       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
-          });
+          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}`,
@@ -3787,10 +6116,14 @@ function createHandlers(registry, actionExecutor, config = {}) {
           } 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
-          });
+          const failureDetails = createFailureDetails(
+            errorCode,
+            actionResult.error || "Action failed",
+            {
+              elementId: id,
+              durationMs: Date.now() - startTime
+            }
+          );
           return success({
             ...actionResult,
             failureDetails
@@ -3889,7 +6222,12 @@ function createHandlers(registry, actionExecutor, config = {}) {
       try {
         const findRequest = request;
         const elements = registry.findElements?.(findRequest) ?? registry.getAllElements();
-        return success({ elements, timestamp: Date.now(), total: elements.length, durationMs: 0 });
+        return success({
+          elements,
+          timestamp: Date.now(),
+          total: elements.length,
+          durationMs: 0
+        });
       } catch (err) {
         return error(err.message, "FIND_ERROR");
       }
@@ -3898,7 +6236,12 @@ function createHandlers(registry, actionExecutor, config = {}) {
       try {
         const findRequest = request;
         const elements = registry.findElements?.(findRequest) ?? registry.getAllElements();
-        return success({ elements, timestamp: Date.now(), total: elements.length, durationMs: 0 });
+        return success({
+          elements,
+          timestamp: Date.now(),
+          total: elements.length,
+          durationMs: 0
+        });
       } catch (err) {
         return error(err.message, "DISCOVER_ERROR");
       }
@@ -3995,6 +6338,28 @@ function createHandlers(registry, actionExecutor, config = {}) {
         return error(err.message, "ELEMENT_TREE_ERROR");
       }
     },
+    getConsoleErrors: async (params) => {
+      try {
+        if (!consoleCapture) {
+          return success({ errors: [], count: 0 });
+        }
+        const errors = params?.since ? consoleCapture.getConsoleSince(params.since) : consoleCapture.getConsoleRecent(params?.limit ?? 50);
+        return success({ errors, count: errors.length });
+      } catch (err) {
+        return error(err.message, "CONSOLE_ERRORS_ERROR");
+      }
+    },
+    clearConsoleErrors: async () => {
+      try {
+        if (!consoleCapture) {
+          return success({ cleared: false });
+        }
+        consoleCapture.clear();
+        return success({ cleared: true });
+      } catch (err) {
+        return error(err.message, "CONSOLE_CLEAR_ERROR");
+      }
+    },
     // =========================================================================
     // AI-Native Handlers
     // =========================================================================
@@ -4013,106 +6378,219 @@ function createHandlers(registry, actionExecutor, config = {}) {
         const response = await nlExecutor.execute(request);
         return success(response);
       } catch (err) {
-        return error(err.message, "AI_EXECUTE_ERROR");
+        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)
+    // =========================================================================
+    // =========================================================================
+    // Page Navigation Handlers
+    // =========================================================================
+    pageRefresh: async () => {
+      try {
+        window.location.reload();
+        return success({ success: true, url: window.location.href, timestamp: Date.now() });
+      } catch (err) {
+        return error(err.message, "PAGE_REFRESH_ERROR");
+      }
+    },
+    pageNavigate: async (request) => {
+      try {
+        if (!request.url) {
+          return error("URL is required", "INVALID_REQUEST");
+        }
+        window.location.href = request.url;
+        return success({ success: true, url: request.url, timestamp: Date.now() });
+      } catch (err) {
+        return error(err.message, "PAGE_NAVIGATE_ERROR");
+      }
+    },
+    pageGoBack: async () => {
+      try {
+        window.history.back();
+        return success({ success: true, url: window.location.href, timestamp: Date.now() });
+      } catch (err) {
+        return error(err.message, "PAGE_GO_BACK_ERROR");
+      }
+    },
+    pageGoForward: async () => {
+      try {
+        window.history.forward();
+        return success({ success: true, url: window.location.href, timestamp: Date.now() });
+      } catch (err) {
+        return error(err.message, "PAGE_GO_FORWARD_ERROR");
+      }
+    },
+    // =========================================================================
+    // Annotation Handlers
+    //
+    // REST API endpoints for managing element annotations:
+    //   GET    /annotations           - List all annotations
+    //   GET    /annotations/export    - Export all annotations as AnnotationConfig
+    //   GET    /annotations/coverage  - Get annotation coverage statistics
+    //   GET    /annotations/:id       - Get annotation for a specific element
+    //   PUT    /annotations/:id       - Create or update an annotation
+    //   DELETE /annotations/:id       - Delete an annotation
+    //   POST   /annotations/import    - Import annotations from AnnotationConfig
+    // =========================================================================
+    getAnnotations: async () => {
+      try {
+        return success(annotationStore.getAll());
+      } catch (err) {
+        return error(err.message, "ANNOTATIONS_ERROR");
+      }
+    },
+    getAnnotation: async (id) => {
+      try {
+        const annotation = annotationStore.get(id);
+        if (!annotation) {
+          return error(`Annotation not found: ${id}`, "NOT_FOUND");
+        }
+        return success(annotation);
+      } catch (err) {
+        return error(err.message, "ANNOTATION_ERROR");
       }
     },
-    aiAssert: async (request) => {
+    setAnnotation: async (id, annotation) => {
       try {
-        refreshElements();
-        const result = await assertionExecutor.assert(request);
-        return success(result);
+        annotationStore.set(id, annotation);
+        return success(annotationStore.get(id));
       } catch (err) {
-        return error(err.message, "AI_ASSERT_ERROR");
+        return error(err.message, "ANNOTATION_SET_ERROR");
       }
     },
-    aiAssertBatch: async (request) => {
+    deleteAnnotation: async (id) => {
       try {
-        refreshElements();
-        const result = await assertionExecutor.assertBatch(request);
-        return success(result);
+        const existed = annotationStore.delete(id);
+        if (!existed) {
+          return error(`Annotation not found: ${id}`, "NOT_FOUND");
+        }
+        return success(void 0);
       } catch (err) {
-        return error(err.message, "AI_ASSERT_BATCH_ERROR");
+        return error(err.message, "ANNOTATION_DELETE_ERROR");
       }
     },
-    getSemanticSnapshot: async () => {
+    importAnnotations: async (config2) => {
       try {
-        const controlSnapshot = registry.createSnapshot();
-        const snapshot = snapshotManager.createSnapshot(controlSnapshot);
-        return success(snapshot);
+        const count = annotationStore.importConfig(config2);
+        return success({ count });
       } catch (err) {
-        return error(err.message, "SEMANTIC_SNAPSHOT_ERROR");
+        return error(err.message, "ANNOTATION_IMPORT_ERROR");
       }
     },
-    getSemanticDiff: async (_since) => {
+    exportAnnotations: async () => {
       try {
-        const controlSnapshot = registry.createSnapshot();
-        const currentSnapshot = snapshotManager.createSnapshot(controlSnapshot);
-        const diff = diffManager.update(currentSnapshot);
-        return success(diff);
+        return success(annotationStore.exportConfig());
       } catch (err) {
-        return error(err.message, "SEMANTIC_DIFF_ERROR");
+        return error(err.message, "ANNOTATION_EXPORT_ERROR");
       }
     },
-    getPageSummary: async () => {
+    getAnnotationCoverage: 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);
+        const allElements = registry.getAllElements();
+        const allIds = allElements.map((el) => el.id);
+        return success(annotationStore.getCoverage(allIds));
       } catch (err) {
-        return error(err.message, "PAGE_SUMMARY_ERROR");
+        return error(err.message, "ANNOTATION_COVERAGE_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);
+        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
+            };
           }
-          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(
@@ -4177,6 +6655,398 @@ function createHandlers(registry, actionExecutor, config = {}) {
       } catch (err) {
         return error(err.message, "AI_SEMANTIC_SEARCH_ERROR");
       }
+    },
+    // =========================================================================
+    // State Management Handlers
+    // =========================================================================
+    getStates: async () => {
+      try {
+        const states = registry.getStates?.() ?? [];
+        return success(states);
+      } catch (err) {
+        return error(err.message, "STATES_ERROR");
+      }
+    },
+    getState: async (id) => {
+      try {
+        const state = registry.getState?.(id);
+        if (!state) {
+          return error(`State not found: ${id}`, "NOT_FOUND");
+        }
+        return success(state);
+      } catch (err) {
+        return error(err.message, "STATE_ERROR");
+      }
+    },
+    getActiveStates: async () => {
+      try {
+        const states = registry.getActiveStates?.() ?? [];
+        return success(states);
+      } catch (err) {
+        return error(err.message, "ACTIVE_STATES_ERROR");
+      }
+    },
+    activateState: async (id) => {
+      try {
+        if (!registry.activateState) {
+          return error("State management not available", "NOT_IMPLEMENTED");
+        }
+        registry.activateState(id);
+        return success(void 0);
+      } catch (err) {
+        return error(err.message, "ACTIVATE_STATE_ERROR");
+      }
+    },
+    deactivateState: async (id) => {
+      try {
+        if (!registry.deactivateState) {
+          return error("State management not available", "NOT_IMPLEMENTED");
+        }
+        registry.deactivateState(id);
+        return success(void 0);
+      } catch (err) {
+        return error(err.message, "DEACTIVATE_STATE_ERROR");
+      }
+    },
+    getStateGroups: async () => {
+      try {
+        const groups = registry.getStateGroups?.() ?? [];
+        return success(groups);
+      } catch (err) {
+        return error(err.message, "STATE_GROUPS_ERROR");
+      }
+    },
+    activateStateGroup: async (id) => {
+      try {
+        if (!registry.activateStateGroup) {
+          return error("State group management not available", "NOT_IMPLEMENTED");
+        }
+        registry.activateStateGroup(id);
+        return success(void 0);
+      } catch (err) {
+        return error(err.message, "ACTIVATE_STATE_GROUP_ERROR");
+      }
+    },
+    deactivateStateGroup: async (id) => {
+      try {
+        if (!registry.deactivateStateGroup) {
+          return error("State group management not available", "NOT_IMPLEMENTED");
+        }
+        registry.deactivateStateGroup(id);
+        return success(void 0);
+      } catch (err) {
+        return error(err.message, "DEACTIVATE_STATE_GROUP_ERROR");
+      }
+    },
+    getTransitions: async () => {
+      try {
+        const transitions = registry.getTransitions?.() ?? [];
+        return success(transitions);
+      } catch (err) {
+        return error(err.message, "TRANSITIONS_ERROR");
+      }
+    },
+    canExecuteTransition: async (id) => {
+      try {
+        if (!registry.canExecuteTransition) {
+          return error("Transition management not available", "NOT_IMPLEMENTED");
+        }
+        const result = registry.canExecuteTransition(id);
+        return success(result);
+      } catch (err) {
+        return error(err.message, "CAN_EXECUTE_TRANSITION_ERROR");
+      }
+    },
+    executeTransition: async (id) => {
+      try {
+        if (!registry.executeTransition) {
+          return error("Transition execution not available", "NOT_IMPLEMENTED");
+        }
+        const result = await registry.executeTransition(id);
+        return success(result);
+      } catch (err) {
+        return error(err.message, "EXECUTE_TRANSITION_ERROR");
+      }
+    },
+    findPath: async (request) => {
+      try {
+        if (!registry.findPath) {
+          return error("Pathfinding not available", "NOT_IMPLEMENTED");
+        }
+        const result = registry.findPath(request.targetStates);
+        return success(result);
+      } catch (err) {
+        return error(err.message, "FIND_PATH_ERROR");
+      }
+    },
+    navigateTo: async (request) => {
+      try {
+        if (!registry.navigateTo) {
+          return error("Navigation not available", "NOT_IMPLEMENTED");
+        }
+        const result = await registry.navigateTo(request.targetStates);
+        return success(result);
+      } catch (err) {
+        return error(err.message, "NAVIGATE_TO_ERROR");
+      }
+    },
+    getStateSnapshot: async () => {
+      try {
+        if (!registry.getStateSnapshot) {
+          const snapshot = {
+            timestamp: Date.now(),
+            activeStates: (registry.getActiveStates?.() ?? []).map((s) => s.id),
+            states: registry.getStates?.() ?? [],
+            groups: registry.getStateGroups?.() ?? [],
+            transitions: registry.getTransitions?.() ?? []
+          };
+          return success(snapshot);
+        }
+        return success(registry.getStateSnapshot());
+      } catch (err) {
+        return error(err.message, "STATE_SNAPSHOT_ERROR");
+      }
+    },
+    // =========================================================================
+    // Intent Handlers
+    // =========================================================================
+    executeIntent: async (request) => {
+      const startTime = Date.now();
+      try {
+        refreshElements();
+        const intent = intentRegistry.get(request.intentId);
+        if (!intent) {
+          return error(`Intent not found: ${request.intentId}`, "NOT_FOUND");
+        }
+        const nlResponse = await nlExecutor.execute({
+          instruction: intent.description,
+          context: `Executing intent: ${intent.name}`
+        });
+        return success({
+          success: nlResponse.success,
+          intentId: request.intentId,
+          result: nlResponse,
+          error: nlResponse.error,
+          durationMs: Date.now() - startTime
+        });
+      } catch (err) {
+        return error(err.message, "EXECUTE_INTENT_ERROR");
+      }
+    },
+    findIntent: async (request) => {
+      try {
+        const query = request.query.toLowerCase();
+        const results = [];
+        for (const intent of intentRegistry.values()) {
+          let confidence = 0;
+          const nameLower = intent.name.toLowerCase();
+          const descLower = intent.description.toLowerCase();
+          if (nameLower === query) {
+            confidence = 1;
+          } else if (nameLower.includes(query) || query.includes(nameLower)) {
+            confidence = 0.8;
+          } else if (descLower.includes(query)) {
+            confidence = 0.6;
+          } else if (intent.tags?.some((t) => t.toLowerCase().includes(query))) {
+            confidence = 0.5;
+          }
+          if (confidence > 0) {
+            results.push({ intent, confidence });
+          }
+        }
+        results.sort((a, b) => b.confidence - a.confidence);
+        return success({ intents: results });
+      } catch (err) {
+        return error(err.message, "FIND_INTENT_ERROR");
+      }
+    },
+    listIntents: async () => {
+      try {
+        return success(Array.from(intentRegistry.values()));
+      } catch (err) {
+        return error(err.message, "LIST_INTENTS_ERROR");
+      }
+    },
+    registerIntent: async (intent) => {
+      try {
+        intentRegistry.set(intent.id, intent);
+        return success(intent);
+      } catch (err) {
+        return error(err.message, "REGISTER_INTENT_ERROR");
+      }
+    },
+    executeIntentFromQuery: async (request) => {
+      const startTime = Date.now();
+      try {
+        refreshElements();
+        const query = request.query.toLowerCase();
+        let bestIntent = null;
+        let bestConfidence = 0;
+        for (const intent of intentRegistry.values()) {
+          let confidence = 0;
+          const nameLower = intent.name.toLowerCase();
+          const descLower = intent.description.toLowerCase();
+          if (nameLower === query) {
+            confidence = 1;
+          } else if (nameLower.includes(query) || query.includes(nameLower)) {
+            confidence = 0.8;
+          } else if (descLower.includes(query)) {
+            confidence = 0.6;
+          }
+          if (confidence > bestConfidence) {
+            bestConfidence = confidence;
+            bestIntent = intent;
+          }
+        }
+        if (!bestIntent) {
+          return success({
+            success: false,
+            intentId: "",
+            error: `No intent found matching query: ${request.query}`,
+            durationMs: Date.now() - startTime
+          });
+        }
+        const nlResponse = await nlExecutor.execute({
+          instruction: bestIntent.description,
+          context: `Executing intent from query: ${request.query}`
+        });
+        return success({
+          success: nlResponse.success,
+          intentId: bestIntent.id,
+          result: nlResponse,
+          error: nlResponse.error,
+          durationMs: Date.now() - startTime
+        });
+      } catch (err) {
+        return error(err.message, "EXECUTE_INTENT_FROM_QUERY_ERROR");
+      }
+    },
+    // =========================================================================
+    // Recovery Handler
+    // =========================================================================
+    attemptRecovery: async (request) => {
+      const startTime = Date.now();
+      try {
+        refreshElements();
+        const strategiesAttempted = [];
+        let lastResult;
+        const suggestions = request.failure.suggestedActions ?? [];
+        for (let i = 0; i < Math.min(suggestions.length, request.maxRetries); i++) {
+          const suggestion = suggestions[i];
+          strategiesAttempted.push(suggestion.suggestion || `strategy-${i}`);
+          const instruction = suggestion.command || request.instruction;
+          try {
+            const result = await nlExecutor.execute({
+              instruction,
+              context: `Recovery attempt ${i + 1}: ${suggestion.suggestion}`
+            });
+            lastResult = result;
+            if (result.success) {
+              return success({
+                recovered: true,
+                strategiesAttempted,
+                finalResult: result,
+                durationMs: Date.now() - startTime
+              });
+            }
+          } catch {
+          }
+        }
+        if (strategiesAttempted.length === 0 || !lastResult?.success) {
+          strategiesAttempted.push("direct-instruction");
+          try {
+            const result = await nlExecutor.execute({
+              instruction: request.instruction,
+              context: "Recovery: direct instruction attempt"
+            });
+            lastResult = result;
+            if (result.success) {
+              return success({
+                recovered: true,
+                strategiesAttempted,
+                finalResult: result,
+                durationMs: Date.now() - startTime
+              });
+            }
+          } catch {
+          }
+        }
+        return success({
+          recovered: false,
+          strategiesAttempted,
+          finalResult: lastResult,
+          error: "All recovery strategies exhausted",
+          durationMs: Date.now() - startTime
+        });
+      } catch (err) {
+        return error(err.message, "RECOVERY_ERROR");
+      }
+    },
+    // =========================================================================
+    // Cross-App Analysis Handlers
+    // =========================================================================
+    analyzePageData: async () => {
+      try {
+        const controlSnapshot = registry.createSnapshot();
+        const snapshot = snapshotManager.createSnapshot(controlSnapshot);
+        const result = extractPageData(snapshot.elements);
+        return success(result);
+      } catch (err) {
+        return error(err.message, "ANALYZE_DATA_ERROR");
+      }
+    },
+    analyzePageRegions: async () => {
+      try {
+        const controlSnapshot = registry.createSnapshot();
+        const snapshot = snapshotManager.createSnapshot(controlSnapshot);
+        const result = segmentPageRegions(snapshot.elements);
+        return success(result);
+      } catch (err) {
+        return error(err.message, "ANALYZE_REGIONS_ERROR");
+      }
+    },
+    analyzeStructuredData: async () => {
+      try {
+        const controlSnapshot = registry.createSnapshot();
+        const snapshot = snapshotManager.createSnapshot(controlSnapshot);
+        const result = extractStructuredData(snapshot.elements);
+        return success(result);
+      } catch (err) {
+        return error(err.message, "ANALYZE_STRUCTURED_DATA_ERROR");
+      }
+    },
+    crossAppCompare: async (request) => {
+      try {
+        const hasComponents = request.sourceComponents && request.targetComponents;
+        const report = generateComparisonReport(
+          request.sourceSnapshot,
+          request.targetSnapshot,
+          hasComponents ? {
+            config: { includeComponents: true },
+            sourceComponents: request.sourceComponents,
+            targetComponents: request.targetComponents
+          } : void 0
+        );
+        return success(report);
+      } catch (err) {
+        return error(err.message, "CROSS_APP_COMPARE_ERROR");
+      }
+    },
+    // =========================================================================
+    // Performance Diagnostics Handlers
+    // =========================================================================
+    getPerformanceEntries: async () => {
+      return {
+        success: true,
+        data: { navigation: null, resources: [], paint: [] },
+        timestamp: Date.now()
+      };
+    },
+    clearPerformanceEntries: async () => {
+      return { success: true, data: { cleared: true }, timestamp: Date.now() };
+    },
+    getBrowserEvents: async (_params) => {
+      return { success: true, data: { events: [], count: 0 }, timestamp: Date.now() };
     }
   };
 }
@@ -4200,7 +7070,12 @@ function createAIHandlers(registry, actionExecutor) {
         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() };
+        return {
+          success: false,
+          error: err.message,
+          code: "AI_SEARCH_ERROR",
+          timestamp: Date.now()
+        };
       }
     },
     aiExecute: async (request) => {
@@ -4209,7 +7084,12 @@ function createAIHandlers(registry, actionExecutor) {
         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() };
+        return {
+          success: false,
+          error: err.message,
+          code: "AI_EXECUTE_ERROR",
+          timestamp: Date.now()
+        };
       }
     },
     aiAssert: async (request) => {
@@ -4218,7 +7098,12 @@ function createAIHandlers(registry, actionExecutor) {
         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() };
+        return {
+          success: false,
+          error: err.message,
+          code: "AI_ASSERT_ERROR",
+          timestamp: Date.now()
+        };
       }
     },
     aiAssertBatch: async (request) => {
@@ -4227,7 +7112,12 @@ function createAIHandlers(registry, actionExecutor) {
         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() };
+        return {
+          success: false,
+          error: err.message,
+          code: "AI_ASSERT_BATCH_ERROR",
+          timestamp: Date.now()
+        };
       }
     },
     getSemanticSnapshot: async () => {
@@ -4236,7 +7126,12 @@ function createAIHandlers(registry, actionExecutor) {
         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() };
+        return {
+          success: false,
+          error: err.message,
+          code: "SEMANTIC_SNAPSHOT_ERROR",
+          timestamp: Date.now()
+        };
       }
     },
     getSemanticDiff: async (_since) => {
@@ -4246,7 +7141,12 @@ function createAIHandlers(registry, actionExecutor) {
         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() };
+        return {
+          success: false,
+          error: err.message,
+          code: "SEMANTIC_DIFF_ERROR",
+          timestamp: Date.now()
+        };
       }
     },
     getPageSummary: async () => {
@@ -4264,7 +7164,12 @@ function createAIHandlers(registry, actionExecutor) {
         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() };
+        return {
+          success: false,
+          error: err.message,
+          code: "PAGE_SUMMARY_ERROR",
+          timestamp: Date.now()
+        };
       }
     }
   };