@midscene/shared 1.5.4-beta-20260310030546.0 → 1.5.4

package/dist/es/cli/cli-runner.mjs

@@ -79,10 +79,18 @@ function printCommandHelp(scriptName, cmd) {
         }
     }
 }
-function printHelp(scriptName, commands) {
+function printVersion(scriptName, version) {
+    console.log(`${scriptName} v${version}`);
+}
+function printHelp(scriptName, commands, version) {
+    if (version) {
+        printVersion(scriptName, version);
+        console.log('');
+    }
     console.log(`\nUsage: ${scriptName} <command> [options]\n`);
     console.log('Commands:');
     for (const { name, def } of commands)console.log(`  ${name.padEnd(30)} ${def.description}`);
+    console.log(`  ${'version'.padEnd(30)} Show CLI version`);
     console.log(`\nRun "${scriptName} <command> --help" for more info.`);
 }
 async function runToolsCLI(tools, scriptName, options) {
@@ -97,17 +105,23 @@ async function runToolsCLI(tools, scriptName, options) {
             name: removePrefix(def.name, options?.stripPrefix).toLowerCase(),
             def
         }));
+    const cliVersion = options?.version;
     const [commandName, ...restArgs] = rawArgs;
     if (!commandName || '--help' === commandName || '-h' === commandName) {
         debug('showing help (no command or --help flag)');
-        printHelp(scriptName, commands);
+        printHelp(scriptName, commands, cliVersion);
+        return;
+    }
+    if ('--version' === commandName || '-v' === commandName || 'version' === commandName.toLowerCase()) {
+        if (!cliVersion) throw new CLIError('Failed to determine CLI version');
+        printVersion(scriptName, cliVersion);
         return;
     }
     const match = commands.find((c)=>c.name.toLowerCase() === commandName.toLowerCase());
     if (!match) {
         debug('unknown command: %s', commandName);
         console.error(`Unknown command: ${commandName}`);
-        printHelp(scriptName, commands);
+        printHelp(scriptName, commands, cliVersion);
         throw new CLIError(`Unknown command: ${commandName}`);
     }
     const parsedArgs = parseCliArgs(restArgs);

package/dist/es/extractor/index.mjs

@@ -1,5 +1,5 @@
 import { descriptionOfTree, traverseTree, treeToList, trimAttributes, truncateText } from "./tree.mjs";
 import { extractTextWithPosition, extractTreeNode, extractTreeNodeAsString } from "./web-extractor.mjs";
-import { getElementInfoByXpath, getElementXpath, getNodeInfoByXpath, getXpathsByPoint } from "./locator.mjs";
+import { getElementInfoByXpath, getElementXpath, getNodeInfoByXpath, getXpathsById, getXpathsByPoint } from "./locator.mjs";
 import { generateElementByRect, isNotContainerElement } from "./dom-util.mjs";
-export { descriptionOfTree, generateElementByRect, getElementInfoByXpath, getElementXpath, getNodeInfoByXpath, getXpathsByPoint, isNotContainerElement, traverseTree, treeToList, trimAttributes, truncateText, extractTreeNode as webExtractNodeTree, extractTreeNodeAsString as webExtractNodeTreeAsString, extractTextWithPosition as webExtractTextWithPosition };
+export { descriptionOfTree, generateElementByRect, getElementInfoByXpath, getElementXpath, getNodeInfoByXpath, getXpathsById, getXpathsByPoint, isNotContainerElement, traverseTree, treeToList, trimAttributes, truncateText, extractTreeNode as webExtractNodeTree, extractTreeNodeAsString as webExtractNodeTreeAsString, extractTextWithPosition as webExtractTextWithPosition };

package/dist/es/extractor/locator.mjs

@@ -1,6 +1,54 @@
 import { isSvgElement } from "./dom-util.mjs";
-import { getRect, isElementPartiallyInViewport } from "./util.mjs";
+import { getNodeFromCacheList, getRect, isElementPartiallyInViewport, logger } from "./util.mjs";
 import { collectElementInfo } from "./web-extractor.mjs";
+const SUB_XPATH_SEPARATOR = '|>>|';
+function parseCSSZoom(style) {
+    return Number.parseFloat(style.zoom ?? '1') || 1;
+}
+function calculateIframeOffset(nodeOwnerDoc, rootDoc) {
+    let leftOffset = 0;
+    let topOffset = 0;
+    let iterDoc = nodeOwnerDoc;
+    while(iterDoc && iterDoc !== rootDoc)try {
+        const frameElement = iterDoc.defaultView?.frameElement;
+        if (!frameElement) break;
+        const rect = frameElement.getBoundingClientRect();
+        const parentWin = iterDoc.defaultView?.parent;
+        let borderLeft = 0;
+        let borderTop = 0;
+        let zoom = 1;
+        try {
+            if (parentWin) {
+                const style = parentWin.getComputedStyle(frameElement);
+                borderLeft = Number.parseFloat(style.borderLeftWidth) || 0;
+                borderTop = Number.parseFloat(style.borderTopWidth) || 0;
+                zoom = parseCSSZoom(style);
+            }
+        } catch  {}
+        leftOffset = leftOffset / zoom + rect.left + borderLeft;
+        topOffset = topOffset / zoom + rect.top + borderTop;
+        iterDoc = frameElement.ownerDocument;
+    } catch  {
+        break;
+    }
+    return {
+        left: leftOffset,
+        top: topOffset
+    };
+}
+function translatePointToIframeCoordinates(point, iframeElement, parentWindow) {
+    const rect = iframeElement.getBoundingClientRect();
+    const style = parentWindow.getComputedStyle(iframeElement);
+    const clientLeft = iframeElement.clientLeft;
+    const clientTop = iframeElement.clientTop;
+    const paddingLeft = Number.parseFloat(style.paddingLeft) || 0;
+    const paddingTop = Number.parseFloat(style.paddingTop) || 0;
+    const zoom = parseCSSZoom(style);
+    return {
+        left: (point.left - rect.left - clientLeft - paddingLeft) / zoom,
+        top: (point.top - rect.top - clientTop - paddingTop) / zoom
+    };
+}
 const getElementXpathIndex = (element)=>{
     let index = 1;
     let prev = element.previousElementSibling;
@@ -14,8 +62,8 @@ const normalizeXpathText = (text)=>{
     if ('string' != typeof text) return '';
     return text.replace(/\s+/g, ' ').trim();
 };
-const buildCurrentElementXpath = (element, isOrderSensitive, isLeafElement)=>{
-    const parentPath = element.parentNode ? getElementXpath(element.parentNode, isOrderSensitive) : '';
+const buildCurrentElementXpath = (element, isOrderSensitive, isLeafElement, limitToCurrentDocument = false)=>{
+    const parentPath = element.parentNode ? getElementXpath(element.parentNode, isOrderSensitive, false, limitToCurrentDocument) : '';
     const prefix = parentPath ? `${parentPath}/` : '/';
     const tagName = element.nodeName.toLowerCase();
     const textContent = element.textContent?.trim();
@@ -29,11 +77,11 @@ const buildCurrentElementXpath = (element, isOrderSensitive, isLeafElement)=>{
     const index = getElementXpathIndex(element);
     return `${prefix}${tagSelector}[${index}]`;
 };
-const getElementXpath = (element, isOrderSensitive = false, isLeafElement = false)=>{
+const getElementXpath = (element, isOrderSensitive = false, isLeafElement = false, limitToCurrentDocument = false)=>{
     if (element.nodeType === Node.TEXT_NODE) {
         const parentNode = element.parentNode;
         if (parentNode && parentNode.nodeType === Node.ELEMENT_NODE) {
-            const parentXPath = getElementXpath(parentNode, isOrderSensitive, true);
+            const parentXPath = getElementXpath(parentNode, isOrderSensitive, true, limitToCurrentDocument);
             const textContent = element.textContent?.trim();
             if (textContent) return `${parentXPath}/text()[normalize-space()="${normalizeXpathText(textContent)}"]`;
             return `${parentXPath}/text()`;
@@ -42,58 +90,161 @@ const getElementXpath = (element, isOrderSensitive = false, isLeafElement = fals
     }
     if (element.nodeType !== Node.ELEMENT_NODE) return '';
     const el = element;
-    if (el === document.documentElement) return '/html';
-    if (el === document.body) return '/html/body';
+    try {
+        const nodeName = el.nodeName.toLowerCase();
+        if (el === el.ownerDocument?.documentElement || 'html' === nodeName) {
+            if (!limitToCurrentDocument) {
+                const frameElement = el.ownerDocument?.defaultView?.frameElement;
+                if (frameElement) {
+                    const framePath = getElementXpath(frameElement, isOrderSensitive, false, limitToCurrentDocument);
+                    return `${framePath}${SUB_XPATH_SEPARATOR}/html`;
+                }
+            }
+            return '/html';
+        }
+        if (el === el.ownerDocument?.body || 'body' === nodeName) {
+            if (!limitToCurrentDocument) {
+                const frameElement = el.ownerDocument?.defaultView?.frameElement;
+                if (frameElement) {
+                    const framePath = getElementXpath(frameElement, isOrderSensitive, false, limitToCurrentDocument);
+                    return `${framePath}${SUB_XPATH_SEPARATOR}/html/body`;
+                }
+            }
+            return '/html/body';
+        }
+    } catch (error) {
+        logger('[midscene:locator] ownerDocument access failed:', error);
+        if ('html' === el.nodeName.toLowerCase()) return '/html';
+        if ('body' === el.nodeName.toLowerCase()) return '/html/body';
+    }
     if (isSvgElement(el)) {
         const tagName = el.nodeName.toLowerCase();
-        if ('svg' === tagName) return buildCurrentElementXpath(el, isOrderSensitive, isLeafElement);
+        if ('svg' === tagName) return buildCurrentElementXpath(el, isOrderSensitive, isLeafElement, limitToCurrentDocument);
         let parent = el.parentNode;
         while(parent && parent.nodeType === Node.ELEMENT_NODE){
             const parentEl = parent;
-            if (!isSvgElement(parentEl)) return getElementXpath(parentEl, isOrderSensitive, isLeafElement);
-            {
-                const parentTag = parentEl.nodeName.toLowerCase();
-                if ('svg' === parentTag) return getElementXpath(parentEl, isOrderSensitive, isLeafElement);
-            }
+            if (!isSvgElement(parentEl)) return getElementXpath(parentEl, isOrderSensitive, isLeafElement, limitToCurrentDocument);
+            const parentTag = parentEl.nodeName.toLowerCase();
+            if ('svg' === parentTag) return getElementXpath(parentEl, isOrderSensitive, isLeafElement, limitToCurrentDocument);
             parent = parent.parentNode;
         }
         const fallbackParent = el.parentNode;
-        if (fallbackParent && fallbackParent.nodeType === Node.ELEMENT_NODE) return getElementXpath(fallbackParent, isOrderSensitive, isLeafElement);
+        if (fallbackParent && fallbackParent.nodeType === Node.ELEMENT_NODE) return getElementXpath(fallbackParent, isOrderSensitive, isLeafElement, limitToCurrentDocument);
         return '';
     }
-    return buildCurrentElementXpath(el, isOrderSensitive, isLeafElement);
+    return buildCurrentElementXpath(el, isOrderSensitive, isLeafElement, limitToCurrentDocument);
 };
-function getXpathsByPoint(point, isOrderSensitive) {
-    const element = document.elementFromPoint(point.left, point.top);
-    if (!element) return null;
-    const fullXPath = getElementXpath(element, isOrderSensitive, true);
+function getXpathsById(id) {
+    const node = getNodeFromCacheList(id);
+    if (!node) return null;
+    const fullXPath = getElementXpath(node, false, true, true);
     return [
         fullXPath
     ];
 }
+function getXpathsByPoint(point, isOrderSensitive) {
+    let currentWindow = 'undefined' != typeof window ? window : void 0;
+    let currentDocument = 'undefined' != typeof document ? document : void 0;
+    let { left, top } = point;
+    let depth = 0;
+    const MAX_DEPTH = 10;
+    let xpathPrefix = '';
+    let lastFoundElement = null;
+    while(depth < MAX_DEPTH){
+        depth++;
+        const element = currentDocument.elementFromPoint(left, top);
+        if (!element) {
+            if (lastFoundElement) {
+                const fullXPath = getElementXpath(lastFoundElement, isOrderSensitive, true, true);
+                return [
+                    xpathPrefix + fullXPath
+                ];
+            }
+            return null;
+        }
+        lastFoundElement = element;
+        const tag = element.tagName.toLowerCase();
+        if ('iframe' === tag || 'frame' === tag) try {
+            const contentWindow = element.contentWindow;
+            const contentDocument = element.contentDocument;
+            if (contentWindow && contentDocument) {
+                const localPoint = translatePointToIframeCoordinates({
+                    left,
+                    top
+                }, element, currentWindow);
+                const currentIframeXpath = getElementXpath(element, isOrderSensitive, false, true);
+                xpathPrefix += currentIframeXpath + SUB_XPATH_SEPARATOR;
+                currentWindow = contentWindow;
+                currentDocument = contentDocument;
+                left = localPoint.left;
+                top = localPoint.top;
+                continue;
+            }
+        } catch (error) {
+            logger('[midscene:locator] iframe penetration failed (cross-origin?):', error);
+        }
+        const fullXPath = getElementXpath(element, isOrderSensitive, true, true);
+        return [
+            xpathPrefix + fullXPath
+        ];
+    }
+    if (lastFoundElement) {
+        const fullXPath = getElementXpath(lastFoundElement, isOrderSensitive, true, true);
+        return [
+            xpathPrefix + fullXPath
+        ];
+    }
+    return null;
+}
 function getNodeInfoByXpath(xpath) {
-    const xpathResult = document.evaluate(xpath, document, null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null);
-    if (1 !== xpathResult.snapshotLength) {
-        console.warn(`[midscene:warning] Received XPath "${xpath}" but it matched ${xpathResult.snapshotLength} elements. Discarding this result.`);
-        return null;
+    const parts = xpath.split(SUB_XPATH_SEPARATOR).map((p)=>p.trim()).filter(Boolean);
+    if (0 === parts.length) return null;
+    let currentDocument = 'undefined' != typeof document ? document : void 0;
+    let node = null;
+    for(let i = 0; i < parts.length; i++){
+        const currentXpath = parts[i];
+        const xpathResult = currentDocument.evaluate(currentXpath, currentDocument, null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null);
+        if (1 !== xpathResult.snapshotLength) {
+            logger(`[midscene:locator] XPath "${currentXpath}" matched ${xpathResult.snapshotLength} elements (expected 1), discarding.`);
+            return null;
+        }
+        node = xpathResult.snapshotItem(0);
+        if (i < parts.length - 1) if (!node || node.nodeType !== Node.ELEMENT_NODE || 'iframe' !== node.tagName.toLowerCase()) return null;
+        else try {
+            const contentDocument = node.contentDocument;
+            if (contentDocument) currentDocument = contentDocument;
+            else {
+                logger('[midscene:locator] iframe contentDocument is null (cross-origin?)');
+                return null;
+            }
+        } catch (error) {
+            logger('[midscene:locator] iframe contentDocument access failed:', error);
+            return null;
+        }
     }
-    const node = xpathResult.snapshotItem(0);
     return node;
 }
 function getElementInfoByXpath(xpath) {
     const node = getNodeInfoByXpath(xpath);
     if (!node) return null;
-    if (node instanceof Element) {
-        const rect = getRect(node, 1, window);
-        const isVisible = isElementPartiallyInViewport(rect, window, document, 1);
+    let targetWindow = 'undefined' != typeof window ? window : void 0;
+    let targetDocument = 'undefined' != typeof document ? document : void 0;
+    if (node.ownerDocument?.defaultView) {
+        targetWindow = node.ownerDocument.defaultView;
+        targetDocument = node.ownerDocument;
+    }
+    const rootDoc = 'undefined' != typeof document ? document : null;
+    const iframeOffset = calculateIframeOffset(node.ownerDocument ?? null, rootDoc);
+    const targetWin = targetWindow;
+    const targetDoc = targetDocument;
+    if (node instanceof targetWin.HTMLElement) {
+        const rect = getRect(node, 1, targetWin);
+        const isVisible = isElementPartiallyInViewport(rect, targetWin, targetDoc, 1);
         if (!isVisible) node.scrollIntoView({
             behavior: 'instant',
             block: 'center'
         });
     }
-    return collectElementInfo(node, window, document, 1, {
-        left: 0,
-        top: 0
-    }, true);
+    return collectElementInfo(node, targetWin, targetDoc, 1, iframeOffset, true);
 }
-export { getElementInfoByXpath, getElementXpath, getNodeInfoByXpath, getXpathsByPoint };
+export { getElementInfoByXpath, getElementXpath, getNodeInfoByXpath, getXpathsById, getXpathsByPoint };

package/dist/es/extractor/util.mjs

@@ -197,8 +197,33 @@ function getNodeAttributes(node, currentWindow) {
     });
     return Object.fromEntries(attributesList);
 }
+const NODE_CACHE_MAX_SIZE = 2000;
+function setNodeHashCacheListOnWindow() {
+    if ('undefined' != typeof window) window.midsceneNodeHashCache = new Map();
+}
+function getNodeCacheMap() {
+    if ('undefined' == typeof window) return;
+    return window.midsceneNodeHashCache;
+}
+function setNodeToCacheList(node, id) {
+    const cache = getNodeCacheMap();
+    if (!cache) return;
+    if (cache.has(id)) return;
+    if (cache.size >= NODE_CACHE_MAX_SIZE) {
+        const firstKey = cache.keys().next().value;
+        if (void 0 !== firstKey) cache.delete(firstKey);
+    }
+    cache.set(id, node);
+}
+function getNodeFromCacheList(id) {
+    return getNodeCacheMap()?.get(id);
+}
 function midsceneGenerateHash(node, content, rect) {
     const slicedHash = generateHashId(rect, content);
+    if (node) {
+        if ('undefined' != typeof window && !getNodeCacheMap()) setNodeHashCacheListOnWindow();
+        setNodeToCacheList(node, slicedHash);
+    }
     return slicedHash;
 }
 function generateId(numberId) {
@@ -217,4 +242,4 @@ function getTopDocument() {
     const container = document.body || document;
     return container;
 }
-export { elementRect, generateId, getDebugMode, getNodeAttributes, getPseudoElementContent, getRect, getTopDocument, hasOverflowY, isElementPartiallyInViewport, logger, midsceneGenerateHash, overlappedRect, setDebugMode, setExtractTextWithPositionOnWindow, setGenerateHashOnWindow, setMidsceneVisibleRectOnWindow, validTextNodeContent };
+export { elementRect, generateId, getDebugMode, getNodeAttributes, getNodeFromCacheList, getPseudoElementContent, getRect, getTopDocument, hasOverflowY, isElementPartiallyInViewport, logger, midsceneGenerateHash, overlappedRect, setDebugMode, setExtractTextWithPositionOnWindow, setGenerateHashOnWindow, setMidsceneVisibleRectOnWindow, setNodeHashCacheListOnWindow, setNodeToCacheList, validTextNodeContent };