ff-automationv2 2.2.0 → 2.2.5

package/dist/utils/iframesExtraction/findElementUsingFF.js

@@ -0,0 +1,32 @@
+import { switchToIframeByMeta } from "./switchToIframeByMeta.js";
+export const findElementUsingFF = async (args) => {
+    await args.driver.switchToFrame(null);
+    const usedElementNames = [];
+    for (const frameMeta of args.frames) {
+        const xpathUsed = await switchToIframeByMeta(args.driver, frameMeta);
+        if (xpathUsed) {
+            let finalElementName = args.elementName;
+            if (finalElementName) {
+                const baseName = finalElementName;
+                let newName = baseName;
+                let count = 0;
+                while (usedElementNames.includes(newName)) {
+                    count++;
+                    newName = `${baseName}_${count}`;
+                }
+                finalElementName = newName;
+                usedElementNames.push(finalElementName);
+            }
+            args.scriptDataAppender.add(async () => ({
+                nlpName: 'SwitchToFrameByFrameElement',
+                stepInputs: [],
+                elementsData: [{
+                        name: finalElementName,
+                        type: args.elementType,
+                        locators: [{ name: "xpath", value: xpathUsed }],
+                        platform: args.platform
+                    }]
+            }));
+        }
+    }
+};

package/dist/utils/iframesExtraction/iframeInterface.d.ts

@@ -0,0 +1,17 @@
+import { ScriptDataAppender } from "../../fireflinkData/fireflinkScript/scriptGenrationData";
+export interface FrameMeta {
+    id?: string;
+    name?: string;
+    title?: string;
+    aria?: string;
+    src?: string;
+}
+export interface IFindElementUsingFF {
+    driver: WebdriverIO.Browser;
+    selector: string;
+    frames: FrameMeta[];
+    scriptDataAppender: ScriptDataAppender;
+    elementName: string;
+    elementType: string;
+    platform: string;
+}

package/dist/utils/iframesExtraction/iframeInterface.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/iframesExtraction/switchToIframeByMeta.d.ts

@@ -0,0 +1,2 @@
+import { FrameMeta } from "./iframeInterface.js";
+export declare function switchToIframeByMeta(driver: WebdriverIO.Browser, frameMeta: FrameMeta): Promise<string | null>;

package/dist/utils/iframesExtraction/switchToIframeByMeta.js

@@ -0,0 +1,22 @@
+export async function switchToIframeByMeta(driver, frameMeta) {
+    const selectors = [
+        frameMeta.id && `//*[@id='${frameMeta.id}']`,
+        frameMeta.name && `//*[@name='${frameMeta.name}']`,
+        frameMeta.title && `//iframe[@title='${frameMeta.title}']`,
+        frameMeta.aria && `//iframe[@aria-label='${frameMeta.aria}']`,
+        frameMeta.src && `//iframe[contains(@src,'${frameMeta.src}')]`,
+    ].filter(Boolean);
+    for (const selector of selectors) {
+        try {
+            const iframe = await driver.$(selector);
+            if (await iframe.isExisting()) {
+                await driver.switchToFrame(iframe);
+                return selector;
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}

package/dist/utils/javascript/jsFindElement.d.ts

@@ -0,0 +1 @@
+export declare const Find_element_by_ff_js_script = "\n  const target = arguments[0];\n  const callback = arguments[arguments.length - 1];\n\n  const MAX_WAIT = 2000;\n  const INTERVAL = 50;\n  const start = Date.now();\n\n  // ---------------- FINDER ----------------\n  function findByFfInspect(root) {\n      const visited = new Set();\n      const stack = [{ node: root, frames: [], currentDoc: root }];\n\n      while (stack.length > 0) {\n          const { node, frames, currentDoc } = stack.pop();\n          if (!node) continue;\n\n          if (\n              node.nodeType === Node.DOCUMENT_NODE ||\n              node.nodeType === Node.DOCUMENT_FRAGMENT_NODE\n          ) {\n              if (visited.has(node)) continue;\n              visited.add(node);\n          }\n\n          if (node.nodeType === Node.ELEMENT_NODE) {\n\n              if (node.getAttribute && node.getAttribute(\"ff-inspect\") === target) {\n                  return { node, frames, iframe_dom: currentDoc };\n              }\n\n              // Shadow DOM\n              if (node.shadowRoot) {\n                  stack.push({\n                      node: node.shadowRoot,\n                      frames,\n                      currentDoc\n                  });\n              }\n\n              // Iframe traversal\n              if (node.tagName === \"IFRAME\") {\n                  try {\n                      const doc = node.contentDocument || node.contentWindow?.document;\n                      if (doc) {\n                          const meta = {\n                              id: node.id || null,\n                              name: node.getAttribute(\"name\") || null,\n                              title: node.getAttribute(\"title\") || null,\n                              aria: node.getAttribute(\"aria-label\") || null,\n                              src: node.getAttribute(\"src\") || null,\n                          };\n\n                          stack.push({\n                              node: doc,\n                              frames: [...frames, meta],\n                              currentDoc: doc\n                          });\n                      }\n                  } catch (e) {}\n              }\n\n              const kids = node.children || node.childNodes;\n              for (let i = kids.length - 1; i >= 0; i--) {\n                  stack.push({ node: kids[i], frames, currentDoc });\n              }\n          }\n\n          else if (\n              node.nodeType === Node.DOCUMENT_NODE ||\n              node.nodeType === Node.DOCUMENT_FRAGMENT_NODE\n          ) {\n              const kids = node.childNodes;\n              for (let i = kids.length - 1; i >= 0; i--) {\n                  stack.push({ node: kids[i], frames, currentDoc });\n              }\n          }\n      }\n\n      return null;\n  }\n\n  // ---------------- CLICKABILITY ----------------\n  function isClickable(el) {\n      if (!el || el.nodeType !== Node.ELEMENT_NODE) return false;\n      const tag = el.tagName.toLowerCase();\n      if (tag === \"button\" || tag === \"a\") return true;\n      if (el.getAttribute(\"role\") === \"button\") return true;\n      if (tag === \"input\") {\n          const t = (el.getAttribute(\"type\") || \"\").toLowerCase();\n          return t === \"button\" || t === \"submit\";\n      }\n      return false;\n  }\n\n  function findClickableInside(root) {\n      const queue = [root];\n      while (queue.length) {\n          const node = queue.shift();\n          if (isClickable(node)) return node;\n          const kids = node.children || node.childNodes;\n          for (let k of kids) queue.push(k);\n      }\n      return null;\n  }\n\n  // ---------------- XPATH BUILDER ----------------\n  function buildXPath(el) {\n      if (!el) return null;\n\n      if (el.id) return \"//*[@id=\\\"\" + el.id + \"\\\"]\";\n\n      const name = el.getAttribute(\"name\");\n      if (name) return \"//*[@name=\\\"\" + name + \"\\\"]\";\n\n      const text = el.textContent && el.textContent.trim();\n      if (text && text.length < 50) {\n          const escaped = text.replace(/\"/g, '\\\"');\n          const xp = \"//*[text()=\\\"\" + escaped + \"\\\"]\";\n          try {\n              const n = document.evaluate(xp, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null);\n              if (n.singleNodeValue === el) return xp;\n          } catch {}\n      }\n\n      const parts = [];\n      let node = el;\n\n      while (node && node.nodeType === Node.ELEMENT_NODE) {\n          let idx = 1;\n          let sib = node.previousSibling;\n          while (sib) {\n              if (sib.nodeType === Node.ELEMENT_NODE && sib.nodeName === node.nodeName) idx++;\n              sib = sib.previousSibling;\n          }\n          parts.unshift(node.nodeName.toLowerCase() + \"[\" + idx + \"]\");\n          node = node.parentNode instanceof ShadowRoot ? node.parentNode.host : node.parentNode;\n      }\n\n      return \"/\" + parts.join(\"/\");\n  }\n\n  // ---------------- WAIT LOOP ----------------\n  (function attempt() {\n      const found = findByFfInspect(document);\n\n      if (!found) {\n          if (Date.now() - start > MAX_WAIT) {\n              return callback({ success: false, reason: \"timeout\" });\n          }\n          return setTimeout(attempt, INTERVAL);\n      }\n\n      let targetNode = found.node;\n      if (!isClickable(targetNode)) {\n          const inside = findClickableInside(targetNode);\n          if (inside) targetNode = inside;\n      }\n\n      const xpath_if = buildXPath(targetNode);\n\n      return callback({\n          success: true,\n          xpath_if,\n          frames: found.frames,\n          iframe_dom_html: found.iframe_dom?.documentElement?.outerHTML || null\n      });\n  })();\n";

package/dist/utils/javascript/jsFindElement.js

@@ -0,0 +1,169 @@
+export const Find_element_by_ff_js_script = `
+  const target = arguments[0];
+  const callback = arguments[arguments.length - 1];
+
+  const MAX_WAIT = 2000;
+  const INTERVAL = 50;
+  const start = Date.now();
+
+  // ---------------- FINDER ----------------
+  function findByFfInspect(root) {
+      const visited = new Set();
+      const stack = [{ node: root, frames: [], currentDoc: root }];
+
+      while (stack.length > 0) {
+          const { node, frames, currentDoc } = stack.pop();
+          if (!node) continue;
+
+          if (
+              node.nodeType === Node.DOCUMENT_NODE ||
+              node.nodeType === Node.DOCUMENT_FRAGMENT_NODE
+          ) {
+              if (visited.has(node)) continue;
+              visited.add(node);
+          }
+
+          if (node.nodeType === Node.ELEMENT_NODE) {
+
+              if (node.getAttribute && node.getAttribute("ff-inspect") === target) {
+                  return { node, frames, iframe_dom: currentDoc };
+              }
+
+              // Shadow DOM
+              if (node.shadowRoot) {
+                  stack.push({
+                      node: node.shadowRoot,
+                      frames,
+                      currentDoc
+                  });
+              }
+
+              // Iframe traversal
+              if (node.tagName === "IFRAME") {
+                  try {
+                      const doc = node.contentDocument || node.contentWindow?.document;
+                      if (doc) {
+                          const meta = {
+                              id: node.id || null,
+                              name: node.getAttribute("name") || null,
+                              title: node.getAttribute("title") || null,
+                              aria: node.getAttribute("aria-label") || null,
+                              src: node.getAttribute("src") || null,
+                          };
+
+                          stack.push({
+                              node: doc,
+                              frames: [...frames, meta],
+                              currentDoc: doc
+                          });
+                      }
+                  } catch (e) {}
+              }
+
+              const kids = node.children || node.childNodes;
+              for (let i = kids.length - 1; i >= 0; i--) {
+                  stack.push({ node: kids[i], frames, currentDoc });
+              }
+          }
+
+          else if (
+              node.nodeType === Node.DOCUMENT_NODE ||
+              node.nodeType === Node.DOCUMENT_FRAGMENT_NODE
+          ) {
+              const kids = node.childNodes;
+              for (let i = kids.length - 1; i >= 0; i--) {
+                  stack.push({ node: kids[i], frames, currentDoc });
+              }
+          }
+      }
+
+      return null;
+  }
+
+  // ---------------- CLICKABILITY ----------------
+  function isClickable(el) {
+      if (!el || el.nodeType !== Node.ELEMENT_NODE) return false;
+      const tag = el.tagName.toLowerCase();
+      if (tag === "button" || tag === "a") return true;
+      if (el.getAttribute("role") === "button") return true;
+      if (tag === "input") {
+          const t = (el.getAttribute("type") || "").toLowerCase();
+          return t === "button" || t === "submit";
+      }
+      return false;
+  }
+
+  function findClickableInside(root) {
+      const queue = [root];
+      while (queue.length) {
+          const node = queue.shift();
+          if (isClickable(node)) return node;
+          const kids = node.children || node.childNodes;
+          for (let k of kids) queue.push(k);
+      }
+      return null;
+  }
+
+  // ---------------- XPATH BUILDER ----------------
+  function buildXPath(el) {
+      if (!el) return null;
+
+      if (el.id) return "//*[@id=\\"" + el.id + "\\"]";
+
+      const name = el.getAttribute("name");
+      if (name) return "//*[@name=\\"" + name + "\\"]";
+
+      const text = el.textContent && el.textContent.trim();
+      if (text && text.length < 50) {
+          const escaped = text.replace(/"/g, '\\"');
+          const xp = "//*[text()=\\"" + escaped + "\\"]";
+          try {
+              const n = document.evaluate(xp, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null);
+              if (n.singleNodeValue === el) return xp;
+          } catch {}
+      }
+
+      const parts = [];
+      let node = el;
+
+      while (node && node.nodeType === Node.ELEMENT_NODE) {
+          let idx = 1;
+          let sib = node.previousSibling;
+          while (sib) {
+              if (sib.nodeType === Node.ELEMENT_NODE && sib.nodeName === node.nodeName) idx++;
+              sib = sib.previousSibling;
+          }
+          parts.unshift(node.nodeName.toLowerCase() + "[" + idx + "]");
+          node = node.parentNode instanceof ShadowRoot ? node.parentNode.host : node.parentNode;
+      }
+
+      return "/" + parts.join("/");
+  }
+
+  // ---------------- WAIT LOOP ----------------
+  (function attempt() {
+      const found = findByFfInspect(document);
+
+      if (!found) {
+          if (Date.now() - start > MAX_WAIT) {
+              return callback({ success: false, reason: "timeout" });
+          }
+          return setTimeout(attempt, INTERVAL);
+      }
+
+      let targetNode = found.node;
+      if (!isClickable(targetNode)) {
+          const inside = findClickableInside(targetNode);
+          if (inside) targetNode = inside;
+      }
+
+      const xpath_if = buildXPath(targetNode);
+
+      return callback({
+          success: true,
+          xpath_if,
+          frames: found.frames,
+          iframe_dom_html: found.iframe_dom?.documentElement?.outerHTML || null
+      });
+  })();
+`;

package/dist/utils/javascript/jsForShadowRoot.d.ts

@@ -0,0 +1,6 @@
+export declare const SHADOW_DOM_CLICK_JS = "\nconst path = arguments[0];\n\nfunction resolve(path) {\n\n  function toCss(sel) {\n    return sel.replace(/(\\w+)\\[(\\d+)\\]/g,\n      (_, t, n) => `${t}:nth-of-type(${n})`);\n  }\n\n  const parts = path.split(\"/shadow/\");\n  let node = document.evaluate(\n    parts[0],\n    document,\n    null,\n    XPathResult.FIRST_ORDERED_NODE_TYPE,\n    null\n  ).singleNodeValue;\n\n  for (let i = 1; i < parts.length; i++) {\n    node = node.shadowRoot.querySelector(\n      toCss(parts[i].replace(/\\//g, \" > \"))\n    );\n  }\n\n  return node;\n}\n\nconst targetNode = resolve(path);\nif (targetNode) {\n  targetNode.click();\n  return true;\n}\nreturn false;\n";
+export declare const SHADOW_DOM_ENTER_JS = "\nconst path = arguments[0];\nconst value = arguments[1];\n\nfunction resolve(path) {\n\n  function toCss(sel) {\n    return sel.replace(/(\\w+)\\[(\\d+)\\]/g,\n      (_, t, n) => `${t}:nth-of-type(${n})`);\n  }\n\n  const parts = path.split(\"/shadow/\");\n  let node = document.evaluate(\n    parts[0],\n    document,\n    null,\n    XPathResult.FIRST_ORDERED_NODE_TYPE,\n    null\n  ).singleNodeValue;\n\n  for (let i = 1; i < parts.length; i++) {\n    node = node.shadowRoot.querySelector(\n      toCss(parts[i].replace(/\\//g, \" > \"))\n    );\n  }\n\n  return node;\n}\n\nconst el = resolve(path);\nif (el) {\n  el.focus();\n  el.value = \"\";\n  el.value = value;\n  el.dispatchEvent(new Event(\"input\", { bubbles: true }));\n  el.dispatchEvent(new Event(\"change\", { bubbles: true }));\n  return true;\n}\nreturn false;\n";
+export declare const SHADOW_DOM_UPLOAD_JS = "\nconst path = arguments[0];\n\nfunction resolve(path) {\n\n  function toCss(sel) {\n    return sel.replace(/(\\w+)\\[(\\d+)\\]/g,\n      (_, t, n) => `${t}:nth-of-type(${n})`);\n  }\n\n  const parts = path.split(\"/shadow/\");\n  let node = document.evaluate(\n    parts[0],\n    document,\n    null,\n    XPathResult.FIRST_ORDERED_NODE_TYPE,\n    null\n  ).singleNodeValue;\n\n  for (let i = 1; i < parts.length; i++) {\n    node = node.shadowRoot.querySelector(\n      toCss(parts[i].replace(/\\//g, \" > \"))\n    );\n  }\n\n  return node;\n}\n\nreturn resolve(path);\n";
+export declare const SHADOW_DOM_GET_TEXT_JS = "\nconst path = arguments[0];\n\nfunction resolve(path) {\n\n  function toCss(sel) {\n    return sel.replace(/(\\w+)\\[(\\d+)\\]/g,\n      (_, t, n) => `${t}:nth-of-type(${n})`);\n  }\n\n  const parts = path.split(\"/shadow/\");\n\n  let node = document.evaluate(\n    parts[0],\n    document,\n    null,\n    XPathResult.FIRST_ORDERED_NODE_TYPE,\n    null\n  ).singleNodeValue;\n\n  for (let i = 1; i < parts.length; i++) {\n    if (!node || !node.shadowRoot) return null;\n    node = node.shadowRoot.querySelector(\n      toCss(parts[i].replace(/\\//g, \" > \"))\n    );\n  }\n\n  return node;\n}\n\nconst el = resolve(path);\nreturn el ? el.innerText.trim() : null;\n";
+export declare const SHADOW_DOM_VERIFY_TEXT_JS = "\nconst path = arguments[0];\nconst text = arguments[1];\n\nfunction resolve(path) {\n\n  function toCss(sel) {\n    return sel.replace(/(\\w+)\\[(\\d+)\\]/g,\n      (_, t, n) => `${t}:nth-of-type(${n})`);\n  }\n\n  const parts = path.split(\"/shadow/\");\n\n  let node = document.evaluate(\n    parts[0],\n    document,\n    null,\n    XPathResult.FIRST_ORDERED_NODE_TYPE,\n    null\n  ).singleNodeValue;\n\n  for (let i = 1; i < parts.length; i++) {\n    if (!node || !node.shadowRoot) return null;\n    node = node.shadowRoot.querySelector(\n      toCss(parts[i].replace(/\\//g, \" > \"))\n    );\n  }\n\n  return node;\n}\n\nconst el = resolve(path);\nreturn el ? el.innerText.trim() === text : false;\n";
+export declare const SHADOW_DOM_VERIFY_PARTIAL_TEXT_JS = "\nconst path = arguments[0];\nconst expected = arguments[1];\n\nfunction resolve(path) {\n\n  function toCss(sel) {\n    return sel.replace(/(\\w+)\\[(\\d+)\\]/g,\n      (_, t, n) => `${t}:nth-of-type(${n})`);\n  }\n\n  const parts = path.split(\"/shadow/\");\n\n  let node = document.evaluate(\n    parts[0],\n    document,\n    null,\n    XPathResult.FIRST_ORDERED_NODE_TYPE,\n    null\n  ).singleNodeValue;\n\n  for (let i = 1; i < parts.length; i++) {\n    if (!node || !node.shadowRoot) return null;\n    node = node.shadowRoot.querySelector(\n      toCss(parts[i].replace(/\\//g, \" > \"))\n    );\n  }\n\n  return node;\n}\n\nconst el = resolve(path);\nif (!el) return false;\n\nconst text = el.innerText ? el.innerText.trim() : \"\";\nreturn text.includes(expected);\n";

package/dist/utils/javascript/jsForShadowRoot.js

@@ -0,0 +1,209 @@
+export const SHADOW_DOM_CLICK_JS = `
+const path = arguments[0];
+
+function resolve(path) {
+
+  function toCss(sel) {
+    return sel.replace(/(\\w+)\\[(\\d+)\\]/g,
+      (_, t, n) => \`\${t}:nth-of-type(\${n})\`);
+  }
+
+  const parts = path.split("/shadow/");
+  let node = document.evaluate(
+    parts[0],
+    document,
+    null,
+    XPathResult.FIRST_ORDERED_NODE_TYPE,
+    null
+  ).singleNodeValue;
+
+  for (let i = 1; i < parts.length; i++) {
+    node = node.shadowRoot.querySelector(
+      toCss(parts[i].replace(/\\//g, " > "))
+    );
+  }
+
+  return node;
+}
+
+const targetNode = resolve(path);
+if (targetNode) {
+  targetNode.click();
+  return true;
+}
+return false;
+`;
+export const SHADOW_DOM_ENTER_JS = `
+const path = arguments[0];
+const value = arguments[1];
+
+function resolve(path) {
+
+  function toCss(sel) {
+    return sel.replace(/(\\w+)\\[(\\d+)\\]/g,
+      (_, t, n) => \`\${t}:nth-of-type(\${n})\`);
+  }
+
+  const parts = path.split("/shadow/");
+  let node = document.evaluate(
+    parts[0],
+    document,
+    null,
+    XPathResult.FIRST_ORDERED_NODE_TYPE,
+    null
+  ).singleNodeValue;
+
+  for (let i = 1; i < parts.length; i++) {
+    node = node.shadowRoot.querySelector(
+      toCss(parts[i].replace(/\\//g, " > "))
+    );
+  }
+
+  return node;
+}
+
+const el = resolve(path);
+if (el) {
+  el.focus();
+  el.value = "";
+  el.value = value;
+  el.dispatchEvent(new Event("input", { bubbles: true }));
+  el.dispatchEvent(new Event("change", { bubbles: true }));
+  return true;
+}
+return false;
+`;
+export const SHADOW_DOM_UPLOAD_JS = `
+const path = arguments[0];
+
+function resolve(path) {
+
+  function toCss(sel) {
+    return sel.replace(/(\\w+)\\[(\\d+)\\]/g,
+      (_, t, n) => \`\${t}:nth-of-type(\${n})\`);
+  }
+
+  const parts = path.split("/shadow/");
+  let node = document.evaluate(
+    parts[0],
+    document,
+    null,
+    XPathResult.FIRST_ORDERED_NODE_TYPE,
+    null
+  ).singleNodeValue;
+
+  for (let i = 1; i < parts.length; i++) {
+    node = node.shadowRoot.querySelector(
+      toCss(parts[i].replace(/\\//g, " > "))
+    );
+  }
+
+  return node;
+}
+
+return resolve(path);
+`;
+export const SHADOW_DOM_GET_TEXT_JS = `
+const path = arguments[0];
+
+function resolve(path) {
+
+  function toCss(sel) {
+    return sel.replace(/(\\w+)\\[(\\d+)\\]/g,
+      (_, t, n) => \`\${t}:nth-of-type(\${n})\`);
+  }
+
+  const parts = path.split("/shadow/");
+
+  let node = document.evaluate(
+    parts[0],
+    document,
+    null,
+    XPathResult.FIRST_ORDERED_NODE_TYPE,
+    null
+  ).singleNodeValue;
+
+  for (let i = 1; i < parts.length; i++) {
+    if (!node || !node.shadowRoot) return null;
+    node = node.shadowRoot.querySelector(
+      toCss(parts[i].replace(/\\//g, " > "))
+    );
+  }
+
+  return node;
+}
+
+const el = resolve(path);
+return el ? el.innerText.trim() : null;
+`;
+export const SHADOW_DOM_VERIFY_TEXT_JS = `
+const path = arguments[0];
+const text = arguments[1];
+
+function resolve(path) {
+
+  function toCss(sel) {
+    return sel.replace(/(\\w+)\\[(\\d+)\\]/g,
+      (_, t, n) => \`\${t}:nth-of-type(\${n})\`);
+  }
+
+  const parts = path.split("/shadow/");
+
+  let node = document.evaluate(
+    parts[0],
+    document,
+    null,
+    XPathResult.FIRST_ORDERED_NODE_TYPE,
+    null
+  ).singleNodeValue;
+
+  for (let i = 1; i < parts.length; i++) {
+    if (!node || !node.shadowRoot) return null;
+    node = node.shadowRoot.querySelector(
+      toCss(parts[i].replace(/\\//g, " > "))
+    );
+  }
+
+  return node;
+}
+
+const el = resolve(path);
+return el ? el.innerText.trim() === text : false;
+`;
+export const SHADOW_DOM_VERIFY_PARTIAL_TEXT_JS = `
+const path = arguments[0];
+const expected = arguments[1];
+
+function resolve(path) {
+
+  function toCss(sel) {
+    return sel.replace(/(\\w+)\\[(\\d+)\\]/g,
+      (_, t, n) => \`\${t}:nth-of-type(\${n})\`);
+  }
+
+  const parts = path.split("/shadow/");
+
+  let node = document.evaluate(
+    parts[0],
+    document,
+    null,
+    XPathResult.FIRST_ORDERED_NODE_TYPE,
+    null
+  ).singleNodeValue;
+
+  for (let i = 1; i < parts.length; i++) {
+    if (!node || !node.shadowRoot) return null;
+    node = node.shadowRoot.querySelector(
+      toCss(parts[i].replace(/\\//g, " > "))
+    );
+  }
+
+  return node;
+}
+
+const el = resolve(path);
+if (!el) return false;
+
+const text = el.innerText ? el.innerText.trim() : "";
+return text.includes(expected);
+`;

package/dist/utils/javascript/jsForToaster.d.ts

@@ -0,0 +1 @@
+export declare const TOAST_WATCHER_JS = "\n(function () {\n\n  // --- STOP any old watcher first ---\n  if (window.__toastObserver) {\n    try { window.__toastObserver.disconnect(); } catch(e) {}\n  }\n\n  // --- Reset state for this step ---\n  window.__toastDetected = false;\n  window.__lastToastText = null;\n\n  function isVisible(el) {\n    const r = el.getBoundingClientRect();\n    const s = getComputedStyle(el);\n    return r.width > 0 && r.height > 0 &&\n           s.display !== \"none\" &&\n           s.visibility !== \"hidden\" &&\n           s.opacity !== \"0\";\n  }\n\n  const observer = new MutationObserver(muts => {\n    for (const m of muts) {\n\n      // New elements\n      for (const node of m.addedNodes || []) {\n        if (node.nodeType !== 1) continue;\n        const text = node.innerText?.trim();\n        if (!text || text.length < 3 || text.length > 300) continue;\n        if (!isVisible(node)) continue;\n\n        window.__toastDetected = true;\n        window.__lastToastText = text;\n        return;\n      }\n\n      // Text changes\n      if (m.type === \"characterData\") {\n        const el = m.target.parentElement;\n        if (!el) continue;\n        const text = el.innerText?.trim();\n        if (!text || text.length < 3 || text.length > 300) continue;\n        if (!isVisible(el)) continue;\n\n        window.__toastDetected = true;\n        window.__lastToastText = text;\n        return;\n      }\n    }\n  });\n\n  observer.observe(document.body, {\n    childList: true,\n    subtree: true,\n    characterData: true\n  });\n\n  window.__toastObserver = observer;\n})();\n";

package/dist/utils/javascript/jsForToaster.js

@@ -0,0 +1,60 @@
+export const TOAST_WATCHER_JS = `
+(function () {
+
+  // --- STOP any old watcher first ---
+  if (window.__toastObserver) {
+    try { window.__toastObserver.disconnect(); } catch(e) {}
+  }
+
+  // --- Reset state for this step ---
+  window.__toastDetected = false;
+  window.__lastToastText = null;
+
+  function isVisible(el) {
+    const r = el.getBoundingClientRect();
+    const s = getComputedStyle(el);
+    return r.width > 0 && r.height > 0 &&
+           s.display !== "none" &&
+           s.visibility !== "hidden" &&
+           s.opacity !== "0";
+  }
+
+  const observer = new MutationObserver(muts => {
+    for (const m of muts) {
+
+      // New elements
+      for (const node of m.addedNodes || []) {
+        if (node.nodeType !== 1) continue;
+        const text = node.innerText?.trim();
+        if (!text || text.length < 3 || text.length > 300) continue;
+        if (!isVisible(node)) continue;
+
+        window.__toastDetected = true;
+        window.__lastToastText = text;
+        return;
+      }
+
+      // Text changes
+      if (m.type === "characterData") {
+        const el = m.target.parentElement;
+        if (!el) continue;
+        const text = el.innerText?.trim();
+        if (!text || text.length < 3 || text.length > 300) continue;
+        if (!isVisible(el)) continue;
+
+        window.__toastDetected = true;
+        window.__lastToastText = text;
+        return;
+      }
+    }
+  });
+
+  observer.observe(document.body, {
+    childList: true,
+    subtree: true,
+    characterData: true
+  });
+
+  window.__toastObserver = observer;
+})();
+`;

package/dist/utils/javascript/jsForVision.d.ts

@@ -0,0 +1,2 @@
+export declare const JS_PRIMARY = "return (function() {\n\n    function isReallyVisible(n) {\n    const r = n.getBoundingClientRect();\n    if (r.width === 0 || r.height === 0) return false;\n\n    const cx = r.x + r.width / 2;\n    const cy = r.y + r.height / 2;\n\n    let topEl = document.elementFromPoint(cx, cy);\n    if (!topEl) return false;\n\n    return n === topEl || n.contains(topEl);\n}\n\n   function isPrimary(n) {\n    const tag = n.tagName.toLowerCase();\n    const text = (n.innerText || \"\").trim();\n    const style = window.getComputedStyle(n);\n\n    if ([\"input\", \"button\", \"select\", \"textarea\"].includes(tag))\n        return true;\n\n    if (tag === \"label\" && text.length > 0)\n        return true;\n\n    if (tag === \"a\" && text.length > 0)\n        return true;\n\n    if (tag === \"li\") {\n        if (text.length > 0 && style.cursor === \"pointer\")\n            return true;\n    }\n\n    return false;\n}\n    function getBBox(n) {\n        const r = n.getBoundingClientRect();\n        return {x:r.x, y:r.y, w:r.width, h:r.height};\n    }\n\n    function collectShadowAware(root, out) {\n        if (!root) return;\n\n        if (root.nodeType === Node.ELEMENT_NODE && root.hasAttribute(\"ff-inspect\"))\n            out.push(root);\n\n        for (const child of root.children) {\n            collectShadowAware(child, out);\n            if (child.shadowRoot) collectShadowAware(child.shadowRoot, out);\n        }\n    }\n\n    const all = [];\n    collectShadowAware(document.documentElement, all);\n\n    const out = [];\n\n    for (let n of all) {\n        if (isReallyVisible(n) && isPrimary(n)) {\n            out.push({\n                ff: n.getAttribute(\"ff-inspect\"),\n                xpath: n.getAttribute(\"ff-xpath\"),\n                bbox: getBBox(n),\n                tag: n.tagName.toLowerCase(),\n                text: (n.innerText || \"\").trim()\n            });\n        }\n    }\n\n    return out;\n})();\n";
+export declare const JS_SECONDARY = "return (function() {\n\n    function isReallyVisible(n) {\n    const r = n.getBoundingClientRect();\n    if (r.width === 0 || r.height === 0) return false;\n\n    const cx = r.x + r.width / 2;\n    const cy = r.y + r.height / 2;\n\n    let topEl = document.elementFromPoint(cx, cy);\n    if (!topEl) return false;\n\n    return n === topEl || n.contains(topEl);\n}\n\n    function isSecondary(n) {\n        const r = n.getBoundingClientRect();\n        const tag = n.tagName.toLowerCase();\n        const text = (n.innerText || \"\").trim();\n        const style = window.getComputedStyle(n);\n\n        if (r.y < 120 && text.length > 0 && text.length <= 12)\n            return true;\n\n        if ([\"div\", \"span\"].includes(tag)) {\n            if (text.length > 0 && text.length <= 20 && r.height > 10)\n                return true;\n            if (style.cursor === \"pointer\")\n                return true;\n        }\n\n        if (tag === \"li\") {\n            if (text.length > 0 || style.cursor === \"pointer\")\n                return true;\n        }\n\n        return false;\n    }\n\n    function getBBox(n) {\n        const r = n.getBoundingClientRect();\n        return {x:r.x, y:r.y, w:r.width, h:r.height};\n    }\n\n    function collectShadowAware(root, out) {\n        if (!root) return;\n\n        if (root.nodeType === Node.ELEMENT_NODE && root.hasAttribute(\"ff-inspect\"))\n            out.push(root);\n\n        for (const child of root.children) {\n            collectShadowAware(child, out);\n            if (child.shadowRoot) collectShadowAware(child.shadowRoot, out);\n        }\n    }\n\n    const all = [];\n    collectShadowAware(document.documentElement, all);\n\n    const out = [];\n\n    for (let n of all) {\n        if (isReallyVisible(n) && isSecondary(n)) {\n            out.push({\n                ff: n.getAttribute(\"ff-inspect\"),\n                xpath: n.getAttribute(\"ff-xpath\"),\n                bbox: getBBox(n),\n                tag: n.tagName.toLowerCase(),\n                text: (n.innerText || \"\").trim()\n            });\n        }\n    }\n\n    return out;\n})();";