@xpert-ai/chatkit-host-automation 0.3.3 → 0.3.4

package/dist/index.d.ts

@@ -4,6 +4,15 @@ export declare function createHostPageAutomationClientToolHandler(options?: Host
 
 export declare const HOST_PAGE_AUTOMATION_TOOL_NAMES: readonly ["host_page_snapshot", "host_page_click", "host_page_fill", "host_page_press", "host_page_select", "host_page_scroll", "host_page_navigate", "host_page_hover", "host_page_focus", "host_page_pointer", "host_page_screenshot", "host_page_wait_for"];
 
+declare type HostPageAutomationClickEffectContext = {
+    point: {
+        x: number;
+        y: number;
+    };
+    target: Element;
+    requested?: Element;
+};
+
 export declare type HostPageAutomationClientToolCall = {
     name: string;
     params?: Record<string, unknown>;
@@ -18,10 +27,19 @@ export declare type HostPageAutomationElementSnapshot = {
     tag: string;
     role?: string;
     name?: string;
+    label?: string;
+    groupLabel?: string;
     text?: string;
     nearbyText?: string[];
     testId?: string;
     value?: string;
+    selectedLabel?: string;
+    options?: Array<{
+        label: string;
+        value: string;
+        selected?: boolean;
+        disabled?: boolean;
+    }>;
     placeholder?: string;
     selector?: string;
     disabled?: boolean;
@@ -77,6 +95,7 @@ export declare class HostPageAutomationExecutor {
     private focus;
     private pointer;
     private screenshot;
+    private showVisualEffect;
     private waitFor;
     private tryResolveElement;
     private describeElement;
@@ -86,10 +105,36 @@ export declare type HostPageAutomationOptions = {
     enabled?: boolean;
     root?: Document | ShadowRoot;
     allowNavigation?: boolean;
+    showVisualEffect?: (context: HostPageAutomationVisualEffectContext) => Promise<void> | void;
+    showClickEffect?: (context: HostPageAutomationClickEffectContext) => Promise<void> | void;
 };
 
 export declare type HostPageAutomationToolName = (typeof HOST_PAGE_AUTOMATION_TOOL_NAMES)[number];
 
+declare type HostPageAutomationVisualEffectContext = {
+    type: HostPageAutomationVisualEffectType;
+    point?: {
+        x: number;
+        y: number;
+    };
+    anchor?: 'target' | 'point';
+    target?: Element;
+    requested?: Element;
+    action?: 'move' | 'down' | 'up' | 'click';
+    key?: string;
+    value?: string;
+    values?: string[];
+    state?: 'attached' | 'visible' | 'hidden' | 'detached';
+    deltaX?: number;
+    deltaY?: number;
+    scroll?: {
+        x: number;
+        y: number;
+    };
+};
+
+declare type HostPageAutomationVisualEffectType = 'click' | 'fill' | 'select' | 'press' | 'scroll' | 'hover' | 'focus' | 'pointer' | 'wait_for' | 'screenshot';
+
 export declare type HostPageSnapshot = {
     url: string;
     title: string;

package/dist/index.js

@@ -1,4 +1,4 @@
-const z = [
+const tt = [
   "host_page_snapshot",
   "host_page_click",
   "host_page_fill",
@@ -11,9 +11,9 @@ const z = [
   "host_page_pointer",
   "host_page_screenshot",
   "host_page_wait_for"
-], G = new Set(
-  z
-), K = [
+], et = new Set(
+  tt
+), nt = [
   "a[href]",
   "button",
   "input",
@@ -28,116 +28,243 @@ const z = [
   "[data-testid]",
   "[data-test-id]",
   "[data-qa]"
-].join(","), D = 100, J = 1e4, Q = 6e4;
-function Z(t) {
-  return G.has(t);
+].join(","), $ = 100, ot = 1e4, rt = 6e4;
+function it(t) {
+  return et.has(t);
 }
-function g(t) {
+function m(t) {
   return t instanceof Document ? t : t.ownerDocument;
 }
-function N(t) {
-  return g(t).defaultView ?? window;
+function H(t) {
+  return m(t).defaultView ?? window;
 }
-function h(t) {
+function y(t) {
   return typeof t == "object" && t !== null && !Array.isArray(t) ? t : {};
 }
-function R(t, e) {
+function O(t, e) {
   if (typeof t != "string" || t.trim() === "")
     throw new Error(`${e} must be a non-empty string.`);
   return t;
 }
-function p(t) {
+function v(t) {
   return typeof t == "string" && t.trim() ? t : void 0;
 }
-function tt(t) {
+function st(t) {
   return typeof t == "number" && Number.isInteger(t) ? t : void 0;
 }
-function M(t, e) {
+function C(t, e) {
   if (typeof t != "number" || !Number.isFinite(t))
     throw new Error(`${e} must be a finite number.`);
   return t;
 }
-function T(t) {
+function _(t) {
   return typeof t == "number" && Number.isFinite(t) ? t : void 0;
 }
-function F(t, e) {
+function W(t, e) {
   return typeof t == "string" && e.includes(t) ? t : void 0;
 }
-function et(t) {
+function ct(t) {
   if (typeof t == "string")
     return [t];
   if (Array.isArray(t) && t.every((e) => typeof e == "string"))
     return t;
   throw new Error("value or values must be a string or an array of strings.");
 }
-function v(t) {
+function b(t) {
   const e = (t.textContent ?? "").replace(/\s+/g, " ").trim();
   return e ? e.slice(0, 160) : void 0;
 }
-function V(t) {
+function R(t) {
   const e = Array.from(t.childNodes).filter((n) => n.nodeType === Node.TEXT_NODE).map((n) => n.textContent ?? "").join(" ").replace(/\s+/g, " ").trim();
   return e ? e.slice(0, 160) : void 0;
 }
-function nt(t) {
+function at(t) {
   if (t instanceof HTMLInputElement || t instanceof HTMLTextAreaElement || t instanceof HTMLSelectElement)
     return t.value;
 }
-function E(t) {
-  const e = t.getAttribute("aria-label");
-  if (e != null && e.trim())
-    return e.trim();
-  const n = t.getAttribute("title");
-  if (n != null && n.trim())
-    return n.trim();
-  if (t instanceof HTMLInputElement) {
-    const r = Array.from(t.labels ?? []).map((c) => v(c)).filter(Boolean);
-    if (r.length > 0)
-      return r.join(" ").slice(0, 160);
+function G(t) {
+  return t instanceof HTMLInputElement && (t.type === "checkbox" || t.type === "radio");
+}
+function lt(t) {
+  return t instanceof HTMLInputElement || t instanceof HTMLSelectElement || t instanceof HTMLTextAreaElement ? Array.from(t.labels ?? []) : [];
+}
+function ut(t, e) {
+  var o;
+  return (((o = t.getAttribute(e)) == null ? void 0 : o.trim().split(/\s+/)) ?? []).map((r) => t.ownerDocument.getElementById(r)).filter((r) => !!r).map((r) => b(r)).filter((r) => !!r);
+}
+function ft(t) {
+  const e = ut(t, "aria-labelledby");
+  if (e.length > 0)
+    return e.join(" ").slice(0, 160);
+  const n = lt(t).map((o) => b(o)).filter((o) => !!o);
+  if (n.length > 0)
+    return n.join(" ").slice(0, 160);
+}
+function dt(t) {
+  const e = [];
+  let n = t.nextSibling;
+  for (; n; ) {
+    if (n.nodeType === Node.TEXT_NODE) {
+      const r = (n.textContent ?? "").replace(/\s+/g, " ").trim();
+      r && e.push(r);
+    } else {
+      if (n.nodeType === Node.ELEMENT_NODE && n.tagName.toLowerCase() === "br")
+        break;
+      if (n.nodeType === Node.ELEMENT_NODE) {
+        const r = n;
+        if (r.matches(
+          'input,textarea,select,button,a[href],[role="button"],[role="link"]'
+        ))
+          break;
+        const c = b(r);
+        c && e.push(c);
+        break;
+      }
+    }
+    if (e.join(" ").length >= 120)
+      break;
+    n = n.nextSibling;
   }
-  const o = X(t)[0];
-  return o || v(t);
+  const o = e.join(" ").replace(/\s+/g, " ").trim();
+  return o ? o.slice(0, 160) : void 0;
 }
-function ot(t) {
-  if (!(t instanceof HTMLElement || t instanceof SVGElement) || !m(t) || t.matches(
+function X(t, e) {
+  var d;
+  const n = t.ownerDocument, o = n.body;
+  if (!o)
+    return;
+  const r = t.getBoundingClientRect();
+  if (r.width <= 0 || r.height <= 0)
+    return;
+  const c = r.top + r.height / 2, i = [], s = n.createTreeWalker(o, NodeFilter.SHOW_ELEMENT);
+  let a = s.nextNode();
+  for (; a; ) {
+    const l = a;
+    if (l !== t && !l.contains(t) && B(l)) {
+      const u = l.getBoundingClientRect(), f = R(l) ?? b(l);
+      if (f) {
+        const h = u.top + u.height / 2, E = Math.abs(h - c) <= Math.max(28, r.height * 1.25), g = e === "left" ? r.left - u.right : u.left - r.right;
+        E && g >= -8 && g <= 240 && i.push({
+          text: f,
+          score: Math.abs(g) + Math.abs(h - c)
+        });
+      }
+    }
+    a = s.nextNode();
+  }
+  return (d = i.sort((l, u) => l.score - u.score)[0]) == null ? void 0 : d.text;
+}
+function z(t) {
+  if (!(t instanceof HTMLInputElement || t instanceof HTMLSelectElement || t instanceof HTMLTextAreaElement))
+    return;
+  const e = ft(t);
+  return e || (G(t) ? X(t, "right") ?? dt(t) ?? N(t)[0] : X(t, "left") ?? N(t)[0]);
+}
+function j(t, e) {
+  const n = e.trim().toLowerCase();
+  return t instanceof HTMLInputElement && t.type === "radio" ? n === "radio" || n === "radio button" : t instanceof HTMLInputElement && t.type === "checkbox" ? n === "checkbox" || n === "check box" : t instanceof HTMLSelectElement ? n === "select" || n === "select menu" || n === "combobox" || n === "combo box" : !1;
+}
+function x(t) {
+  const e = z(t), n = t.getAttribute("aria-label");
+  if (n != null && n.trim() && !j(t, n))
+    return n.trim();
+  const o = t.getAttribute("title");
+  if (o != null && o.trim() && !j(t, o))
+    return o.trim();
+  if (e)
+    return e;
+  const r = N(t)[0];
+  return r || b(t);
+}
+function B(t) {
+  if (!(t instanceof HTMLElement || t instanceof SVGElement) || !T(t) || t.matches(
     'input,textarea,select,button,a[href],[role="button"],[role="link"]'
   ))
     return !1;
-  const e = V(t) ?? v(t);
+  const e = R(t) ?? b(t);
   return !!(e && e.length <= 120);
 }
-function X(t) {
+function ht(t) {
+  var u;
+  if (!G(t))
+    return;
+  const e = t.closest("fieldset"), n = e == null ? void 0 : e.querySelector("legend"), o = n ? b(n) : void 0;
+  if (o)
+    return o;
+  const r = t.ownerDocument, c = r.body;
+  if (!c)
+    return;
+  const i = t.getBoundingClientRect();
+  if (i.width <= 0 || i.height <= 0)
+    return;
+  const s = i.left + i.width / 2, a = [], d = r.createTreeWalker(c, NodeFilter.SHOW_ELEMENT);
+  let l = d.nextNode();
+  for (; l; ) {
+    const f = l;
+    if (f !== t && !f.contains(t) && f.matches('legend,strong,b,[role="heading"],h1,h2,h3,h4,h5,h6') && B(f)) {
+      const h = f.getBoundingClientRect(), E = R(f) ?? b(f);
+      if (E && h.bottom <= i.top + 8) {
+        const g = i.top - h.bottom, w = h.left + h.width / 2;
+        g <= 160 && w >= i.left - 120 && w <= i.right + 320 && a.push({
+          text: E,
+          score: g + Math.abs(w - s) * 0.25
+        });
+      }
+    }
+    l = d.nextNode();
+  }
+  return (u = a.sort((f, h) => f.score - h.score)[0]) == null ? void 0 : u.text;
+}
+function gt(t) {
+  if (!(t instanceof HTMLSelectElement))
+    return;
+  const e = Array.from(t.options).map((n) => ({
+    label: ((n.label || n.textContent || n.value).replace(/\s+/g, " ").trim() || n.value).slice(0, 160),
+    value: n.value,
+    selected: n.selected || void 0,
+    disabled: n.disabled || void 0
+  }));
+  return e.length ? e : void 0;
+}
+function pt(t) {
+  if (!(t instanceof HTMLSelectElement))
+    return;
+  const e = t.selectedOptions[0], n = e ? (e.label || e.textContent || e.value).replace(/\s+/g, " ").trim() : void 0;
+  return n ? n.slice(0, 160) : void 0;
+}
+function N(t) {
   const e = t.ownerDocument, n = e.body;
   if (!n)
     return [];
   const o = t.getBoundingClientRect();
   if (o.width <= 0 || o.height <= 0)
     return [];
-  const r = o.top + o.height / 2, c = o.left + o.width / 2, s = [], i = e.createTreeWalker(n, NodeFilter.SHOW_ELEMENT);
-  let a = i.nextNode();
+  const r = o.top + o.height / 2, c = o.left + o.width / 2, i = [], s = e.createTreeWalker(n, NodeFilter.SHOW_ELEMENT);
+  let a = s.nextNode();
   for (; a; ) {
     const l = a;
-    if (l !== t && ot(l)) {
-      const u = l.getBoundingClientRect(), f = V(l) ?? v(l);
+    if (l !== t && !l.contains(t) && B(l)) {
+      const u = l.getBoundingClientRect(), f = R(l) ?? b(l);
       if (f) {
-        const b = u.top + u.height / 2, w = u.left + u.width / 2, y = u.right <= o.left + 12 && Math.abs(b - r) <= Math.max(28, o.height * 1.25), S = u.bottom <= o.top + 8 && o.top - u.bottom <= 80 && w >= o.left - 80 && w <= o.right + 80;
-        if (y || S) {
-          const j = y ? o.left - u.right + Math.abs(b - r) : o.top - u.bottom + Math.abs(w - c);
-          s.push({
+        const h = u.top + u.height / 2, E = u.left + u.width / 2, g = u.right <= o.left + 12 && Math.abs(h - r) <= Math.max(28, o.height * 1.25), w = u.left >= o.right - 8 && u.left - o.right <= 240 && Math.abs(h - r) <= Math.max(28, o.height * 1.25), q = u.bottom <= o.top + 8 && o.top - u.bottom <= 80 && E >= o.left - 80 && E <= o.right + 80;
+        if (g || w || q) {
+          const Z = g ? o.left - u.right + Math.abs(h - r) : w ? u.left - o.right + Math.abs(h - r) : o.top - u.bottom + Math.abs(E - c);
+          i.push({
             text: f,
-            score: j + (y ? 0 : 100)
+            score: Z + (g ? 0 : w ? 5 : 100)
           });
         }
       }
     }
-    a = i.nextNode();
+    a = s.nextNode();
   }
   const d = /* @__PURE__ */ new Set();
-  return s.sort((l, u) => l.score - u.score).map((l) => l.text).filter((l) => d.has(l) ? !1 : (d.add(l), !0)).slice(0, 4);
+  return i.sort((l, u) => l.score - u.score).map((l) => l.text).filter((l) => d.has(l) ? !1 : (d.add(l), !0)).slice(0, 4);
 }
-function rt(t) {
+function Et(t) {
   return t.getAttribute("data-testid") ?? t.getAttribute("data-test-id") ?? t.getAttribute("data-qa") ?? void 0;
 }
-function x(t) {
+function M(t) {
   const e = t.getAttribute("role");
   if (e != null && e.trim())
     return e.trim();
@@ -161,13 +288,13 @@ function x(t) {
         return "textbox";
     }
 }
-function q(t) {
+function K(t) {
   return t instanceof HTMLButtonElement || t instanceof HTMLInputElement || t instanceof HTMLSelectElement || t instanceof HTMLTextAreaElement ? t.disabled || void 0 : t.getAttribute("aria-disabled") === "true" || void 0;
 }
-function it(t) {
+function bt(t) {
   return t instanceof HTMLInputElement && (t.type === "checkbox" || t.type === "radio") ? t.checked : void 0;
 }
-function st(t) {
+function wt(t) {
   const e = k(t);
   if (!(e.width <= 0 || e.height <= 0))
     return {
@@ -175,37 +302,37 @@ function st(t) {
       y: e.y + e.height / 2
     };
 }
-function $(t) {
+function U(t) {
   return {
     tag: t.tagName.toLowerCase(),
-    role: x(t),
-    name: E(t),
-    selector: P(t)
+    role: M(t),
+    name: x(t),
+    selector: D(t)
   };
 }
-function m(t) {
+function T(t) {
   if (!(t instanceof HTMLElement || t instanceof SVGElement) || t instanceof HTMLElement && t.hidden)
     return !1;
   const e = t.ownerDocument.defaultView, n = e == null ? void 0 : e.getComputedStyle(t);
   return !(n && (n.display === "none" || n.visibility === "hidden" || n.opacity === "0"));
 }
-function U(t) {
-  return t.matches(K) && m(t);
+function J(t) {
+  return t.matches(nt) && T(t);
 }
-function ct(t) {
-  return q(t) !== !0;
+function yt(t) {
+  return K(t) !== !0;
 }
-function at(t) {
+function mt(t) {
   var n;
-  if (U(t))
+  if (J(t))
     return !0;
   if (!(t instanceof HTMLElement))
     return !1;
   const e = (n = t.ownerDocument.defaultView) == null ? void 0 : n.getComputedStyle(t);
-  return ((e == null ? void 0 : e.cursor) === "pointer" || !!t.onclick) && m(t);
+  return ((e == null ? void 0 : e.cursor) === "pointer" || !!t.onclick) && T(t);
 }
 function k(t) {
-  var c, s;
+  var c, i;
   const e = t.getBoundingClientRect();
   let n = e.left, o = e.top, r = null;
   try {
@@ -214,10 +341,10 @@ function k(t) {
     r = null;
   }
   for (; r; ) {
-    const i = r.getBoundingClientRect();
-    n += i.left, o += i.top;
+    const s = r.getBoundingClientRect();
+    n += s.left, o += s.top;
     try {
-      r = ((s = r.ownerDocument.defaultView) == null ? void 0 : s.frameElement) ?? null;
+      r = ((i = r.ownerDocument.defaultView) == null ? void 0 : i.frameElement) ?? null;
     } catch {
       r = null;
     }
@@ -229,7 +356,7 @@ function k(t) {
     height: e.height
   };
 }
-function P(t) {
+function D(t) {
   const e = (o) => typeof CSS < "u" && typeof CSS.escape == "function" ? CSS.escape(o) : o.replaceAll("\\", "\\\\").replaceAll('"', '\\"');
   if (t.id)
     return `#${e(t.id)}`;
@@ -243,7 +370,7 @@ function P(t) {
     n
   )}"]` : t.tagName.toLowerCase();
 }
-function lt(t) {
+function vt(t) {
   const e = t.getBoundingClientRect();
   if (!(e.width <= 0 || e.height <= 0))
     return {
@@ -251,7 +378,7 @@ function lt(t) {
       y: e.top + e.height / 2
     };
 }
-function W(t, e) {
+function Q(t, e) {
   if (typeof t.elementsFromPoint == "function")
     return t.elementsFromPoint(e.x, e.y);
   if (typeof t.elementFromPoint != "function")
@@ -259,25 +386,25 @@ function W(t, e) {
   const n = t.elementFromPoint(e.x, e.y);
   return n ? [n] : [];
 }
-function ut(t) {
+function xt(t) {
   return typeof t.elementsFromPoint == "function" || typeof t.elementFromPoint == "function";
 }
-function C(t, e) {
+function A(t, e) {
   return t === e || t.contains(e);
 }
-function ft(t) {
+function Tt(t) {
   let e = t;
   for (; e; ) {
-    if (at(e))
+    if (mt(e))
       return e;
     e = e.parentElement;
   }
   return t;
 }
-function B(t) {
+function Y(t) {
   return (t ?? "").replace(/\([^)]*\)/g, "").replace(/\s+/g, "").trim().toLowerCase();
 }
-function Y(t) {
+function V(t) {
   const e = t.getBoundingClientRect();
   if (e.width <= 0 || e.height <= 0)
     return;
@@ -289,40 +416,47 @@ function Y(t) {
     { x: e.left + e.width / 2, y: e.top + Math.min(8, e.height / 2) },
     { x: e.left + e.width / 2, y: e.bottom - Math.min(8, e.height / 2) }
   ].find(
-    (r) => W(n, r).some(
-      (c) => C(t, c) || C(c, t)
+    (r) => Q(n, r).some(
+      (c) => A(t, c) || A(c, t)
     )
   );
 }
-function dt(t, e) {
+function Mt(t, e) {
+  const n = t.getBoundingClientRect(), o = k(t);
+  return {
+    x: e.x + o.x - n.left,
+    y: e.y + o.y - n.top
+  };
+}
+function _t(t, e) {
   var c;
-  const n = x(e), o = B(E(e));
-  return o ? ((c = I(t).filter((s) => s !== e).filter((s) => {
-    const i = x(s), a = B(E(s));
-    return n && i && n !== i ? !1 : a.includes(o) || o.includes(a);
-  }).map((s) => ({
-    candidate: s,
-    point: Y(s),
-    rect: k(s)
+  const n = M(e), o = Y(x(e));
+  return o ? ((c = F(t).filter((i) => i !== e).filter((i) => {
+    const s = M(i), a = Y(x(i));
+    return n && s && n !== s ? !1 : a.includes(o) || o.includes(a);
+  }).map((i) => ({
+    candidate: i,
+    point: V(i),
+    rect: k(i)
   })).filter(
-    (s) => !!s.point
-  ).sort((s, i) => i.rect.y - s.rect.y)[0]) == null ? void 0 : c.candidate) ?? null : null;
+    (i) => !!i.point
+  ).sort((i, s) => s.rect.y - i.rect.y)[0]) == null ? void 0 : c.candidate) ?? null : null;
 }
-function L(t) {
-  const e = t.ownerDocument, n = lt(t), o = m(t) && !!n, r = ct(t), c = n ? W(e, n) : [], s = c[0], i = !!(s && (C(t, s) || C(s, t)));
+function p(t) {
+  const e = t.ownerDocument, n = vt(t), o = T(t) && !!n, r = yt(t), c = n ? Q(e, n) : [], i = c[0], s = !!(i && (A(t, i) || A(i, t)));
   return {
     visible: o,
     enabled: r,
-    receivesEvents: i,
-    actionable: o && r && i,
-    center: st(t),
-    hitTarget: s,
+    receivesEvents: s,
+    actionable: o && r && s,
+    center: wt(t),
+    hitTarget: i,
     hitStack: c
   };
 }
-function ht(t, e) {
-  var i, a, d;
-  const n = p(e.testId);
+function St(t, e) {
+  var s, a, d;
+  const n = v(e.testId);
   if (n) {
     const l = typeof CSS < "u" && typeof CSS.escape == "function" ? CSS.escape(n) : n.replaceAll("\\", "\\\\").replaceAll('"', '\\"'), u = t.querySelector(
       `[data-testid="${l}"],[data-test-id="${l}"],[data-qa="${l}"]`
@@ -330,52 +464,52 @@ function ht(t, e) {
     if (u)
       return u;
   }
-  const o = (i = p(e.role)) == null ? void 0 : i.toLowerCase(), r = (a = p(e.name)) == null ? void 0 : a.toLowerCase(), c = (d = p(e.text)) == null ? void 0 : d.toLowerCase();
-  return !o && !r && !c ? null : I(t).find((l) => {
-    var w, y, S;
-    const u = (w = x(l)) == null ? void 0 : w.toLowerCase(), f = (y = E(l)) == null ? void 0 : y.toLowerCase(), b = (S = v(l)) == null ? void 0 : S.toLowerCase();
-    return !(o && u !== o || r && !(f != null && f.includes(r)) || c && !(b != null && b.includes(c)));
+  const o = (s = v(e.role)) == null ? void 0 : s.toLowerCase(), r = (a = v(e.name)) == null ? void 0 : a.toLowerCase(), c = (d = v(e.text)) == null ? void 0 : d.toLowerCase();
+  return !o && !r && !c ? null : F(t).find((l) => {
+    var E, g, w;
+    const u = (E = M(l)) == null ? void 0 : E.toLowerCase(), f = (g = x(l)) == null ? void 0 : g.toLowerCase(), h = (w = b(l)) == null ? void 0 : w.toLowerCase();
+    return !(o && u !== o || r && !(f != null && f.includes(r)) || c && !(h != null && h.includes(c)));
   }) ?? null;
 }
-function I(t) {
-  const e = g(t), n = t instanceof Document ? t.body ?? t.documentElement : t;
+function F(t) {
+  const e = m(t), n = t instanceof Document ? t.body ?? t.documentElement : t;
   if (!n)
     return [];
   const o = [], r = (c) => {
-    const s = e.createTreeWalker(c, NodeFilter.SHOW_ELEMENT);
-    let i = s.nextNode();
-    for (; i; ) {
-      const a = i;
-      U(a) && o.push(a);
+    const i = e.createTreeWalker(c, NodeFilter.SHOW_ELEMENT);
+    let s = i.nextNode();
+    for (; s; ) {
+      const a = s;
+      J(a) && o.push(a);
       const d = a.shadowRoot;
       if (d && r(d), a instanceof HTMLIFrameElement)
         try {
           a.contentDocument && r(a.contentDocument);
         } catch {
         }
-      if (o.length >= D)
+      if (o.length >= $)
         return;
-      i = s.nextNode();
+      s = i.nextNode();
     }
   };
-  return r(n), o.slice(0, D);
+  return r(n), o.slice(0, $);
 }
-function gt(t, e) {
+function Lt(t, e) {
   var r;
   const n = Object.getPrototypeOf(t), o = Object.getOwnPropertyDescriptor(n, "value");
   (r = o == null ? void 0 : o.set) == null || r.call(t, e);
 }
-function H(t) {
+function I(t) {
   t.dispatchEvent(new Event("input", { bubbles: !0 })), t.dispatchEvent(new Event("change", { bubbles: !0 }));
 }
-function A(t) {
+function S(t) {
   var e, n;
   (t instanceof HTMLElement || t instanceof SVGElement) && ((e = t.scrollIntoView) == null || e.call(t, { block: "center", inline: "center" })), t instanceof HTMLElement && ((n = t.focus) == null || n.call(t));
 }
-function _(t, e) {
+function L(t, e) {
   return typeof PointerEvent == "function" ? new PointerEvent(t, e) : new MouseEvent(t.replace("pointer", "mouse"), e);
 }
-class pt {
+class kt {
   constructor(e = {}) {
     this.options = e, this.refs = /* @__PURE__ */ new Map(), this.nextRef = 1;
   }
@@ -410,10 +544,10 @@ class pt {
     }
   }
   snapshot() {
-    var c, s;
+    var c, i;
     this.refs.clear(), this.nextRef = 1;
-    const e = this.getRoot(), n = g(e), o = N(e), r = I(e).map(
-      (i) => this.snapshotElement(i)
+    const e = this.getRoot(), n = m(e), o = H(e), r = F(e).map(
+      (s) => this.snapshotElement(s)
     );
     return {
       url: o.location.href,
@@ -438,18 +572,18 @@ class pt {
         readyState: n.readyState,
         visibilityState: n.visibilityState,
         focusedElement: n.activeElement && n.activeElement !== n.body ? this.snapshotElementWithoutRef(n.activeElement) : void 0,
-        selection: ((s = (c = n.getSelection) == null ? void 0 : c.call(n)) == null ? void 0 : s.toString()) || void 0
+        selection: ((i = (c = n.getSelection) == null ? void 0 : c.call(n)) == null ? void 0 : i.toString()) || void 0
       },
       navigation: this.getNavigationState(o),
       frames: this.getFrameState(n),
-      accessibility: r.map((i) => ({
-        ref: i.ref,
-        role: i.role,
-        name: i.name,
-        value: i.value,
-        disabled: i.disabled,
-        checked: i.checked,
-        focused: n.activeElement === this.refs.get(i.ref)
+      accessibility: r.map((s) => ({
+        ref: s.ref,
+        role: s.role,
+        name: s.name,
+        value: s.value,
+        disabled: s.disabled,
+        checked: s.checked,
+        focused: n.activeElement === this.refs.get(s.ref)
       })),
       elements: r
     };
@@ -496,139 +630,203 @@ class pt {
     return this.createElementSnapshot(e, "");
   }
   createElementSnapshot(e, n) {
-    const o = (e instanceof HTMLInputElement || e instanceof HTMLTextAreaElement) && e.placeholder || void 0, r = L(e);
+    const o = (e instanceof HTMLInputElement || e instanceof HTMLTextAreaElement) && e.placeholder || void 0, r = p(e);
     return {
       ref: n,
       tag: e.tagName.toLowerCase(),
-      role: x(e),
-      name: E(e),
-      text: v(e),
-      nearbyText: X(e),
-      testId: rt(e),
-      value: nt(e),
+      role: M(e),
+      name: x(e),
+      label: z(e),
+      groupLabel: ht(e),
+      text: b(e),
+      nearbyText: N(e),
+      testId: Et(e),
+      value: at(e),
+      selectedLabel: pt(e),
+      options: gt(e),
       placeholder: o,
-      selector: P(e),
-      disabled: q(e),
+      selector: D(e),
+      disabled: K(e),
       enabled: r.enabled,
-      checked: it(e),
+      checked: bt(e),
       visible: r.visible,
       actionable: r.actionable,
       rect: k(e),
       center: r.center,
-      hitTarget: r.hitTarget ? $(r.hitTarget) : void 0,
-      hitStack: r.hitStack.slice(0, 5).map($)
+      hitTarget: r.hitTarget ? U(r.hitTarget) : void 0,
+      hitStack: r.hitStack.slice(0, 5).map(U)
     };
   }
   resolveElement(e) {
-    const n = p(e.ref) ?? p(e.axRef);
+    const n = v(e.ref) ?? v(e.axRef);
     if (n) {
       const c = this.refs.get(n);
       if (!c)
         throw new Error(`Unknown element ref: ${n}. Take a new snapshot.`);
       return c;
     }
-    const o = p(e.selector);
+    const o = v(e.selector);
     if (o) {
       const c = this.getRoot().querySelector(o);
       if (!c)
         throw new Error(`No element matches selector: ${o}.`);
       return c;
     }
-    const r = ht(this.getRoot(), e);
+    const r = St(this.getRoot(), e);
     if (r)
       return r;
     if (typeof e.x < "u" || typeof e.y < "u") {
       const c = {
-        x: M(e.x, "x"),
-        y: M(e.y, "y")
-      }, s = g(this.getRoot()).elementFromPoint(
+        x: C(e.x, "x"),
+        y: C(e.y, "y")
+      }, i = m(this.getRoot()).elementFromPoint(
         c.x,
         c.y
       );
-      if (!s)
+      if (!i)
         throw new Error(`No element found at (${c.x}, ${c.y}).`);
-      return s;
+      return i;
     }
     throw new Error(
       "Expected one of ref, selector, role/name/text/testId, or x/y."
     );
   }
-  click(e) {
-    const n = h(e), o = this.resolveElement(n), r = L(o), s = (r.actionable ? null : dt(this.getRoot(), o)) ?? ft(o), i = Y(s);
-    if (!i && !r.actionable && ut(o.ownerDocument))
+  async click(e) {
+    const n = y(e), o = this.resolveElement(n), r = p(o), i = (r.actionable ? null : _t(this.getRoot(), o)) ?? Tt(o);
+    if (!V(i) && !r.actionable && xt(o.ownerDocument))
       throw new Error(
-        `Target "${E(o) ?? o.tagName.toLowerCase()}" is not receiving pointer events. Take a screenshot or use host_page_pointer coordinates.`
+        `Target "${x(o) ?? o.tagName.toLowerCase()}" is not receiving pointer events. Take a screenshot or use host_page_pointer coordinates.`
       );
-    return A(s), s instanceof HTMLElement ? s.click() : s.dispatchEvent(new MouseEvent("click", { bubbles: !0 })), {
-      clicked: this.describeElement(s),
+    S(i);
+    const a = V(i), d = p(i), l = p(o), u = a ? Mt(i, a) : d.center ?? r.center;
+    return u && await this.showVisualEffect({
+      type: "click",
+      point: u,
+      anchor: "target",
+      target: i,
+      requested: o
+    }), i instanceof HTMLElement ? i.click() : i.dispatchEvent(new MouseEvent("click", { bubbles: !0 })), {
+      clicked: this.describeElement(i),
       requested: this.describeElement(o),
-      strategy: s === o ? "dom" : "semantic_visible_fallback",
-      point: i ?? r.center,
+      strategy: i === o ? "dom" : "semantic_visible_fallback",
+      point: u,
       actionability: {
-        visible: r.visible,
-        enabled: r.enabled,
-        receivesEvents: r.receivesEvents
+        visible: l.visible,
+        enabled: l.enabled,
+        receivesEvents: l.receivesEvents
       }
     };
   }
-  fill(e) {
-    const n = h(e), o = R(n.value, "value"), r = this.resolveElement(n);
-    if (A(r), r instanceof HTMLInputElement || r instanceof HTMLTextAreaElement)
-      return gt(r, o), H(r), { filled: this.describeElement(r), value: o };
+  async fill(e) {
+    const n = y(e), o = O(n.value, "value"), r = this.resolveElement(n);
+    if (S(r), r instanceof HTMLInputElement || r instanceof HTMLTextAreaElement)
+      return await this.showVisualEffect({
+        type: "fill",
+        target: r,
+        requested: r,
+        value: o,
+        anchor: "target",
+        point: p(r).center
+      }), Lt(r, o), I(r), { filled: this.describeElement(r), value: o };
     if (r instanceof HTMLElement && r.isContentEditable)
-      return r.textContent = o, H(r), { filled: this.describeElement(r), value: o };
+      return await this.showVisualEffect({
+        type: "fill",
+        target: r,
+        requested: r,
+        value: o,
+        anchor: "target",
+        point: p(r).center
+      }), r.textContent = o, I(r), { filled: this.describeElement(r), value: o };
     throw new Error("Target element cannot be filled.");
   }
-  press(e) {
-    const n = h(e), o = R(n.key, "key"), r = n.ref || n.selector || n.x !== void 0 && n.y !== void 0 ? this.resolveElement(n) : g(this.getRoot()).activeElement ?? g(this.getRoot()).body;
+  async press(e) {
+    const n = y(e), o = O(n.key, "key"), r = n.ref || n.selector || n.x !== void 0 && n.y !== void 0 ? this.resolveElement(n) : m(this.getRoot()).activeElement ?? m(this.getRoot()).body;
     if (!r)
       throw new Error("No target element is available for key press.");
-    A(r);
+    S(r), await this.showVisualEffect({
+      type: "press",
+      target: r,
+      requested: r,
+      key: o,
+      anchor: "target",
+      point: p(r).center
+    });
     const c = { key: o, bubbles: !0, cancelable: !0 };
     return r.dispatchEvent(new KeyboardEvent("keydown", c)), o.length === 1 && r.dispatchEvent(new KeyboardEvent("keypress", c)), r.dispatchEvent(new KeyboardEvent("keyup", c)), { pressed: o, target: this.describeElement(r) };
   }
-  select(e) {
-    const n = h(e), o = et(n.values ?? n.value), r = this.resolveElement(n);
+  async select(e) {
+    const n = y(e), o = ct(n.values ?? n.value), r = this.resolveElement(n);
     if (!(r instanceof HTMLSelectElement))
       throw new Error("Target element is not a select.");
+    S(r);
     const c = new Set(o);
-    for (const s of Array.from(r.options))
-      s.selected = c.has(s.value);
-    return H(r), {
+    await this.showVisualEffect({
+      type: "select",
+      target: r,
+      requested: r,
+      values: o,
+      anchor: "target",
+      point: p(r).center
+    });
+    for (const i of Array.from(r.options))
+      i.selected = c.has(i.value);
+    return I(r), {
       selected: Array.from(r.selectedOptions).map(
-        (s) => s.value
+        (i) => i.value
       ),
       target: this.describeElement(r)
     };
   }
-  scroll(e) {
+  async scroll(e) {
     var a, d, l, u;
-    const n = h(e), o = n.x !== void 0 || n.y !== void 0 ? {
-      x: T(n.x) ?? 0,
-      y: T(n.y) ?? 0
-    } : null, r = T(n.deltaX) ?? 0, c = T(n.deltaY) ?? 0, s = this.getRoot(), i = N(s);
+    const n = y(e), o = n.x !== void 0 || n.y !== void 0 ? {
+      x: _(n.x) ?? 0,
+      y: _(n.y) ?? 0
+    } : null, r = _(n.deltaX) ?? 0, c = _(n.deltaY) ?? 0, i = this.getRoot(), s = H(i);
     if (n.ref || n.selector || n.role || n.name || n.text || n.testId) {
       const f = this.resolveElement(n);
       if (!(f instanceof HTMLElement))
         throw new Error("Target element cannot be scrolled.");
-      return o ? (a = f.scrollTo) == null || a.call(f, o.x, o.y) : (d = f.scrollBy) == null || d.call(f, r, c), {
+      return await this.showVisualEffect({
+        type: "scroll",
+        target: f,
+        requested: f,
+        deltaX: r,
+        deltaY: c,
+        anchor: "target",
+        point: p(f).center
+      }), o ? (a = f.scrollTo) == null || a.call(f, o.x, o.y) : (d = f.scrollBy) == null || d.call(f, r, c), {
         scrolled: this.describeElement(f),
         scroll: { x: f.scrollLeft, y: f.scrollTop }
       };
     }
-    return o ? (l = i.scrollTo) == null || l.call(i, o.x, o.y) : (u = i.scrollBy) == null || u.call(i, r, c), { scroll: { x: i.scrollX, y: i.scrollY } };
+    return await this.showVisualEffect({
+      type: "scroll",
+      deltaX: r,
+      deltaY: c,
+      point: {
+        x: s.innerWidth / 2,
+        y: s.innerHeight / 2
+      }
+    }), o ? (l = s.scrollTo) == null || l.call(s, o.x, o.y) : (u = s.scrollBy) == null || u.call(s, r, c), { scroll: { x: s.scrollX, y: s.scrollY } };
   }
   navigate(e) {
     if (this.options.allowNavigation === !1)
       throw new Error("Navigation is disabled for host page automation.");
-    const n = h(e), o = this.getRoot(), r = N(o), c = R(n.url, "url"), s = new URL(c, r.location.href);
-    if (s.protocol !== "http:" && s.protocol !== "https:")
+    const n = y(e), o = this.getRoot(), r = H(o), c = O(n.url, "url"), i = new URL(c, r.location.href);
+    if (i.protocol !== "http:" && i.protocol !== "https:")
       throw new Error("Navigation only supports HTTP(S) URLs.");
-    return this.refs.clear(), r.location.assign(s.toString()), { navigated: s.toString() };
+    return this.refs.clear(), r.location.assign(i.toString()), { navigated: i.toString() };
   }
-  hover(e) {
-    const n = h(e), o = this.resolveElement(n), r = L(o).center;
-    return o.dispatchEvent(
+  async hover(e) {
+    const n = y(e), o = this.resolveElement(n), r = p(o).center;
+    return await this.showVisualEffect({
+      type: "hover",
+      target: o,
+      requested: o,
+      anchor: "target",
+      point: r
+    }), o.dispatchEvent(
       new MouseEvent("mouseover", {
         bubbles: !0,
         cancelable: !0,
@@ -644,31 +842,60 @@ class pt {
       })
     ), { hovered: this.describeElement(o), point: r };
   }
-  focus(e) {
-    const n = h(e), o = this.resolveElement(n);
-    return A(o), { focused: this.describeElement(o) };
+  async focus(e) {
+    const n = y(e), o = this.resolveElement(n);
+    return S(o), await this.showVisualEffect({
+      type: "focus",
+      target: o,
+      requested: o,
+      anchor: "target",
+      point: p(o).center
+    }), { focused: this.describeElement(o) };
   }
-  pointer(e) {
-    const n = h(e), o = F(n.action, ["move", "down", "up", "click"]) ?? "click", r = tt(n.button) ?? 0, c = n.ref || n.selector || n.role || n.name || n.text || n.testId ? this.resolveElement(n) : null, s = c ? L(c).center : {
-      x: M(n.x, "x"),
-      y: M(n.y, "y")
+  async pointer(e) {
+    const n = y(e), o = W(n.action, ["move", "down", "up", "click"]) ?? "click", r = st(n.button) ?? 0, c = n.ref || n.selector || n.role || n.name || n.text || n.testId ? this.resolveElement(n) : null, i = c ? p(c).center : {
+      x: C(n.x, "x"),
+      y: C(n.y, "y")
     };
-    if (!s)
-      throw new Error("Target element has no clickable point.");
-    const i = c ?? g(this.getRoot()).elementFromPoint(s.x, s.y);
     if (!i)
-      throw new Error(`No element found at (${s.x}, ${s.y}).`);
+      throw new Error("Target element has no clickable point.");
+    const s = c ?? m(this.getRoot()).elementFromPoint(i.x, i.y);
+    if (!s)
+      throw new Error(`No element found at (${i.x}, ${i.y}).`);
     const a = {
       bubbles: !0,
       cancelable: !0,
-      clientX: s.x,
-      clientY: s.y,
+      clientX: i.x,
+      clientY: i.y,
       button: r
     };
-    return o === "move" ? (i.dispatchEvent(_("pointermove", a)), i.dispatchEvent(new MouseEvent("mousemove", a))) : o === "down" ? (i.dispatchEvent(_("pointerdown", a)), i.dispatchEvent(new MouseEvent("mousedown", a))) : o === "up" ? (i.dispatchEvent(_("pointerup", a)), i.dispatchEvent(new MouseEvent("mouseup", a))) : (i.dispatchEvent(_("pointerdown", a)), i.dispatchEvent(new MouseEvent("mousedown", a)), i.dispatchEvent(_("pointerup", a)), i.dispatchEvent(new MouseEvent("mouseup", a)), i instanceof HTMLElement ? i.click() : i.dispatchEvent(new MouseEvent("click", a))), {
+    return o === "move" ? (await this.showVisualEffect({
+      type: "pointer",
+      action: o,
+      anchor: "point",
+      point: i,
+      target: s
+    }), s.dispatchEvent(L("pointermove", a)), s.dispatchEvent(new MouseEvent("mousemove", a))) : o === "down" ? (await this.showVisualEffect({
+      type: "pointer",
+      action: o,
+      anchor: "point",
+      point: i,
+      target: s
+    }), s.dispatchEvent(L("pointerdown", a)), s.dispatchEvent(new MouseEvent("mousedown", a))) : o === "up" ? (await this.showVisualEffect({
+      type: "pointer",
+      action: o,
+      anchor: "point",
+      point: i,
+      target: s
+    }), s.dispatchEvent(L("pointerup", a)), s.dispatchEvent(new MouseEvent("mouseup", a))) : (await this.showVisualEffect({
+      type: "click",
+      anchor: "point",
+      point: i,
+      target: s
+    }), s.dispatchEvent(L("pointerdown", a)), s.dispatchEvent(new MouseEvent("mousedown", a)), s.dispatchEvent(L("pointerup", a)), s.dispatchEvent(new MouseEvent("mouseup", a)), s instanceof HTMLElement ? s.click() : s.dispatchEvent(new MouseEvent("click", a))), {
       pointer: o,
-      point: s,
-      target: this.describeElement(i)
+      point: i,
+      target: this.describeElement(s)
     };
   }
   screenshot() {
@@ -676,25 +903,48 @@ class pt {
       "host_page_screenshot requires the browser extension CDP adapter."
     );
   }
+  async showVisualEffect(e) {
+    var n, o, r, c;
+    try {
+      await ((o = (n = this.options).showVisualEffect) == null ? void 0 : o.call(n, e));
+    } catch {
+    }
+    if (!(e.type !== "click" || !e.point || !e.target || this.options.showVisualEffect))
+      try {
+        await ((c = (r = this.options).showClickEffect) == null ? void 0 : c.call(r, {
+          point: e.point,
+          target: e.target,
+          requested: e.requested
+        }));
+      } catch {
+      }
+  }
   async waitFor(e) {
-    const n = h(e), o = F(n.state, [
+    const n = y(e), o = W(n.state, [
       "attached",
       "visible",
       "hidden",
       "detached"
-    ]) ?? "visible", r = T(n.timeoutSeconds), c = Math.min(
-      Q,
-      Math.max(0, (r ?? J / 1e3) * 1e3)
-    ), s = Date.now();
-    for (; Date.now() - s <= c; ) {
-      const i = this.tryResolveElement(n);
-      if (o === "attached" ? !!i : o === "detached" ? !i : o === "hidden" ? !i || !m(i) : !!(i && m(i)))
+    ]) ?? "visible", r = _(n.timeoutSeconds), c = Math.min(
+      rt,
+      Math.max(0, (r ?? ot / 1e3) * 1e3)
+    ), i = Date.now(), s = this.tryResolveElement(n);
+    for (await this.showVisualEffect({
+      type: "wait_for",
+      state: o,
+      target: s ?? void 0,
+      requested: s ?? void 0,
+      ...s ? { anchor: "target" } : {},
+      point: s ? p(s).center : void 0
+    }); Date.now() - i <= c; ) {
+      const a = this.tryResolveElement(n);
+      if (o === "attached" ? !!a : o === "detached" ? !a : o === "hidden" ? !a || !T(a) : !!(a && T(a)))
         return {
           waitedFor: o,
-          elapsedMs: Date.now() - s,
-          target: i ? this.describeElement(i) : void 0
+          elapsedMs: Date.now() - i,
+          target: a ? this.describeElement(a) : void 0
         };
-      await new Promise((d) => setTimeout(d, 100));
+      await new Promise((l) => setTimeout(l, 100));
     }
     throw new Error(`Timed out waiting for target to become ${o}.`);
   }
@@ -708,54 +958,54 @@ class pt {
   describeElement(e) {
     return {
       tag: e.tagName.toLowerCase(),
-      role: x(e),
-      name: E(e),
-      selector: P(e)
+      role: M(e),
+      name: x(e),
+      selector: D(e)
     };
   }
 }
-function Et(t) {
+function Ct(t) {
   return typeof t == "object" && t !== null && !Array.isArray(t) ? t : {};
 }
-function mt(t) {
+function Nt(t) {
   return JSON.stringify(t);
 }
-function O(t, e, n) {
+function P(t, e, n) {
   return {
     tool_call_id: t.tool_call_id ?? t.id,
     name: t.name,
     status: e,
-    content: mt(n)
+    content: Nt(n)
   };
 }
-function bt(t) {
+function At(t) {
   return t instanceof Error ? t.message : String(t);
 }
-function wt(t = {}) {
-  const e = new pt(t);
+function Rt(t = {}) {
+  const e = new kt(t);
   return async (n) => {
-    if (!Z(n.name))
-      return O(n, "error", {
+    if (!it(n.name))
+      return P(n, "error", {
         ok: !1,
         error: `Unknown host page automation tool: ${n.name}`
       });
     try {
       const o = await e.execute(
         n.name,
-        Et(n.params)
+        Ct(n.params)
       );
-      return O(n, "success", { ok: !0, result: o });
+      return P(n, "success", { ok: !0, result: o });
     } catch (o) {
-      return O(n, "error", {
+      return P(n, "error", {
         ok: !1,
-        error: bt(o)
+        error: At(o)
       });
     }
   };
 }
 export {
-  z as HOST_PAGE_AUTOMATION_TOOL_NAMES,
-  pt as HostPageAutomationExecutor,
-  wt as createHostPageAutomationClientToolHandler,
-  Z as isHostPageAutomationToolName
+  tt as HOST_PAGE_AUTOMATION_TOOL_NAMES,
+  kt as HostPageAutomationExecutor,
+  Rt as createHostPageAutomationClientToolHandler,
+  it as isHostPageAutomationToolName
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xpert-ai/chatkit-host-automation",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "Host page automation tools for Xpert ChatKit client tools",
   "sideEffects": false,
   "type": "module",
@@ -21,7 +21,7 @@
     "!**/*.tsbuildinfo"
   ],
   "dependencies": {
-    "@xpert-ai/chatkit-types": "~0.3.4"
+    "@xpert-ai/chatkit-types": "~0.3.5"
   },
   "devDependencies": {
     "rimraf": "^6.0.0",