sela-core 1.0.8 → 1.0.9

package/dist/utils/DOMUtils.d.ts

@@ -24,8 +24,24 @@ export declare class DOMUtils {
      */
     private static _getNeighborhoodFromFrame;
     /**
-     * Runs the neighborhood-DOM extraction script inside the given execution
-     * context (either a Page or a Frame).
+     * Runs the "Smart Neighborhood" DOM-extraction script inside the given
+     * execution context (a Page or a Frame). Implements asymmetric scope:
+     *
+     *   - FULL semantic ancestry spine (anchor → root, crossing shadow→host)
+     *     is always kept — this is cheap and carries the critical context
+     *     (form/fieldset/dialog/landmark/id anchors).
+     *   - SIBLINGS are pruned to a fixed K-window around the spine child; the
+     *     number dropped is surfaced via `data-sibling-total` so the AI knows
+     *     pruning occurred (and never assumes a positional selector is safe).
+     *   - GLOBAL uniqueness is probed in the SAME evaluate pass; when the
+     *     anchor's primary signal matches >1 element page-wide, the count is
+     *     attached as `fx-global-matches` — this defeats the "neighborhood is
+     *     unique but the page is not" trap without shipping the whole DOM.
+     *   - Char-budget (cheap proxy for tokens) bounds the final payload.
+     *
+     * Generic wrappers (div/span) with no semantic signal are collapsed; visual
+     * noise (class/style) is stripped; script/style/svg and hidden elements are
+     * dropped. Shadow DOM and same-origin iframe content are pierced and inlined.
      */
     private static _evaluateNeighborhood;
     static getElementDNA: (page: Page, selector: string) => Promise<ElementDNA>;

package/dist/utils/DOMUtils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DOMUtils.d.ts","sourceRoot":"","sources":["../../src/utils/DOMUtils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACxC,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAEtC,qBAAa,QAAQ;IACnB;;;;OAIG;IACH,MAAM,CAAC,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IAKjD;;;;OAIG;IACH,MAAM,CAAC,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE;WAM5B,kBAAkB,CACpC,IAAI,EAAE,IAAI,EACV,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAerD;;;;OAIG;mBACkB,yBAAyB;IAoD9C;;;OAGG;mBACkB,qBAAqB;IAmF1C,MAAM,CAAC,aAAa,GAClB,MAAM,IAAI,EACV,UAAU,MAAM,KACf,OAAO,CAAC,UAAU,CAAC,CAqCpB;CACH"}
+{"version":3,"file":"DOMUtils.d.ts","sourceRoot":"","sources":["../../src/utils/DOMUtils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACxC,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAEtC,qBAAa,QAAQ;IACnB;;;;OAIG;IACH,MAAM,CAAC,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IAKjD;;;;OAIG;IACH,MAAM,CAAC,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE;WAM5B,kBAAkB,CACpC,IAAI,EAAE,IAAI,EACV,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAerD;;;;OAIG;mBACkB,yBAAyB;IAoD9C;;;;;;;;;;;;;;;;;;;OAmBG;mBACkB,qBAAqB;IAoW1C,MAAM,CAAC,aAAa,GAClB,MAAM,IAAI,EACV,UAAU,MAAM,KACf,OAAO,CAAC,UAAU,CAAC,CAqCpB;CACH"}

package/dist/utils/DOMUtils.js

@@ -76,68 +76,354 @@ class DOMUtils {
         }
     }
     /**
-     * Runs the neighborhood-DOM extraction script inside the given execution
-     * context (either a Page or a Frame).
+     * Runs the "Smart Neighborhood" DOM-extraction script inside the given
+     * execution context (a Page or a Frame). Implements asymmetric scope:
+     *
+     *   - FULL semantic ancestry spine (anchor → root, crossing shadow→host)
+     *     is always kept — this is cheap and carries the critical context
+     *     (form/fieldset/dialog/landmark/id anchors).
+     *   - SIBLINGS are pruned to a fixed K-window around the spine child; the
+     *     number dropped is surfaced via `data-sibling-total` so the AI knows
+     *     pruning occurred (and never assumes a positional selector is safe).
+     *   - GLOBAL uniqueness is probed in the SAME evaluate pass; when the
+     *     anchor's primary signal matches >1 element page-wide, the count is
+     *     attached as `fx-global-matches` — this defeats the "neighborhood is
+     *     unique but the page is not" trap without shipping the whole DOM.
+     *   - Char-budget (cheap proxy for tokens) bounds the final payload.
+     *
+     * Generic wrappers (div/span) with no semantic signal are collapsed; visual
+     * noise (class/style) is stripped; script/style/svg and hidden elements are
+     * dropped. Shadow DOM and same-origin iframe content are pierced and inlined.
      */
     static async _evaluateNeighborhood(context, selector) {
-        console.log(`[DOM-EXTRACT] 🧠 Force-Extracting full context DOM for: "${selector}"`);
-        const result = await context.evaluate(() => {
-            let indexCounter = 0;
-            const processNode = (node) => {
-                // 1. טיפול בטקסט
+        console.log(`[DOM-EXTRACT] 🧠 Smart-Neighborhood extraction for: "${selector}"`);
+        const result = await context.evaluate((cfg) => {
+            const { selector, K, maxText, budget } = cfg;
+            // ---- Tag taxonomies ------------------------------------------------
+            const SKIP = new Set([
+                "script",
+                "style",
+                "link",
+                "svg",
+                "noscript",
+                "template",
+                "meta",
+            ]);
+            // Kept verbatim but never directly selectable → no fx-id index.
+            const CONTAINER = new Set([
+                "html",
+                "body",
+                "form",
+                "nav",
+                "section",
+                "header",
+                "footer",
+                "main",
+                "article",
+                "aside",
+                "ul",
+                "ol",
+                "dl",
+                "table",
+                "thead",
+                "tbody",
+                "tfoot",
+                "tr",
+                "colgroup",
+                "fieldset",
+                "figure",
+                "figcaption",
+                "caption",
+                "menu",
+                "details",
+            ]);
+            // Generic layout wrappers: collapsed when they carry no semantic signal.
+            const COLLAPSIBLE = new Set(["div", "span"]);
+            const SIGNAL_ATTRS = ["id", "data-testid", "name", "role", "aria-label"];
+            // Output attribute allow-list (class/style intentionally excluded).
+            const PRESERVED = [
+                "id",
+                "data-testid",
+                "name",
+                "role",
+                "type",
+                "href",
+                "alt",
+                "title",
+                "placeholder",
+                "value",
+                "aria-label",
+                "aria-labelledby",
+                "aria-describedby",
+                "for",
+                "list",
+                "src",
+                "srcdoc",
+            ];
+            const isTransparent = (tag) => tag === "body" || tag === "html";
+            // ---- Deep query: pierce shadow roots + same-origin iframes ---------
+            const deepQuery = (root, sel) => {
+                let found = null;
+                try {
+                    found = root.querySelector(sel);
+                }
+                catch {
+                    found = null;
+                }
+                if (found)
+                    return found;
+                let nodes = [];
+                try {
+                    nodes = Array.from(root.querySelectorAll("*"));
+                }
+                catch {
+                    nodes = [];
+                }
+                for (const e of nodes) {
+                    if (e.shadowRoot) {
+                        const r = deepQuery(e.shadowRoot, sel);
+                        if (r)
+                            return r;
+                    }
+                    if (e.tagName === "IFRAME") {
+                        try {
+                            const d = e.contentDocument;
+                            if (d) {
+                                const r = deepQuery(d, sel);
+                                if (r)
+                                    return r;
+                            }
+                        }
+                        catch {
+                            /* cross-origin frame — skip */
+                        }
+                    }
+                }
+                return null;
+            };
+            // ---- Visibility ----------------------------------------------------
+            const isHidden = (el) => {
+                const e = el;
+                if (e.getAttribute && e.getAttribute("aria-hidden") === "true")
+                    return true;
+                if (e.hasAttribute && e.hasAttribute("hidden"))
+                    return true;
+                if (el.tagName === "INPUT" && e.getAttribute("type") === "hidden")
+                    return true;
+                if (e.style &&
+                    (e.style.display === "none" || e.style.visibility === "hidden"))
+                    return true;
+                try {
+                    const view = el.ownerDocument?.defaultView || window;
+                    const cs = view.getComputedStyle(e);
+                    if (cs && (cs.display === "none" || cs.visibility === "hidden"))
+                        return true;
+                }
+                catch {
+                    /* getComputedStyle across docs may throw — ignore */
+                }
+                return false;
+            };
+            const hasSignal = (el) => SIGNAL_ATTRS.some((a) => !!el.getAttribute?.(a));
+            const containsHeader = (el) => el.tagName === "TH" || !!el.querySelector?.("th");
+            // ---- Anchor + ancestry spine --------------------------------------
+            const anchor = deepQuery(document, selector);
+            const spine = new Set();
+            // Walk an element + all its ancestors into the spine, crossing shadow
+            // boundaries (ShadowRoot, nodeType 11 → host element).
+            const addLineage = (start) => {
+                let cur = start;
+                while (cur) {
+                    spine.add(cur);
+                    if (!cur.parentNode)
+                        break;
+                    cur =
+                        cur.parentNode.nodeType === 11
+                            ? cur.parentNode.host || null
+                            : cur.parentNode;
+                }
+            };
+            if (anchor) {
+                addLineage(anchor);
+                // Detached semantic refs (#14-16): the accessible name/description
+                // may live anywhere in the document, linked only by id. Pull those
+                // nodes (and their lineage) into the spine so pruning never drops
+                // the context the AI needs for getByLabel / aria-based selectors.
+                const refIds = [];
+                ["aria-labelledby", "aria-describedby", "list"].forEach((a) => {
+                    const v = anchor.getAttribute(a);
+                    if (v)
+                        refIds.push(...v.split(/\s+/).filter(Boolean));
+                });
+                refIds.forEach((id) => {
+                    const e = document.getElementById(id);
+                    if (e)
+                        addLineage(e);
+                });
+                // Reverse link: <label for="anchorId"> sitting elsewhere in the DOM.
+                const aid = anchor.getAttribute("id");
+                if (aid) {
+                    try {
+                        document
+                            .querySelectorAll(`label[for="${aid.replace(/(["\\])/g, "\\$1")}"]`)
+                            .forEach((l) => addLineage(l));
+                    }
+                    catch {
+                        /* ignore malformed id */
+                    }
+                }
+            }
+            // ---- Global uniqueness probe (same evaluate pass) -----------------
+            const globalMatches = (el) => {
+                const esc = (v) => v.replace(/(["\\])/g, "\\$1");
+                const testid = el.getAttribute("data-testid");
+                const id = el.getAttribute("id");
+                const name = el.getAttribute("name");
+                const role = el.getAttribute("role");
+                const tag = el.tagName.toLowerCase();
+                let sel = "";
+                if (testid)
+                    sel = `[data-testid="${esc(testid)}"]`;
+                else if (id)
+                    sel = `#${window.CSS?.escape ? CSS.escape(id) : id}`;
+                else if (name)
+                    sel = `${tag}[name="${esc(name)}"]`;
+                else if (role)
+                    sel = `${tag}[role="${esc(role)}"]`;
+                else {
+                    // No stable attr — count same-tag elements sharing trimmed text.
+                    const txt = (el.textContent || "").trim();
+                    if (!txt)
+                        return 1;
+                    let n = 0;
+                    document.querySelectorAll(tag).forEach((c) => {
+                        if ((c.textContent || "").trim() === txt)
+                            n++;
+                    });
+                    return n;
+                }
+                try {
+                    return document.querySelectorAll(sel).length;
+                }
+                catch {
+                    return 1;
+                }
+            };
+            const counter = { v: 0 };
+            const truncate = (s) => s.length > maxText ? s.slice(0, maxText) + "…" : s;
+            const renderNode = (node) => {
+                // --- Text node ---
                 if (node.nodeType === Node.TEXT_NODE) {
-                    const text = node.textContent?.trim();
-                    return text ? text : null;
+                    const t = node.textContent ? node.textContent.trim() : "";
+                    return t ? truncate(t) : null;
                 }
-                // 2. סינון אלמנטים לא רלוונטיים
-                if (node.nodeType !== Node.ELEMENT_NODE &&
-                    !(node instanceof ShadowRoot))
+                const isShadow = typeof ShadowRoot !== "undefined" && node instanceof ShadowRoot;
+                if (node.nodeType !== Node.ELEMENT_NODE && !isShadow)
                     return null;
-                const el = node instanceof ShadowRoot
+                const el = isShadow
                     ? node.host
                     : node;
-                const tag = node instanceof ShadowRoot ? "shadow-root" : el.tagName.toLowerCase();
-                if (["script", "style", "link", "svg"].includes(tag))
+                const tag = isShadow ? "shadow-root" : el.tagName.toLowerCase();
+                if (SKIP.has(tag))
                     return null;
-                // 3. איסוף אטריביוטים
+                if (!isShadow && isHidden(el))
+                    return null;
+                // --- Gather children: shadow root + light DOM + same-doc iframe ---
+                let childNodes = [];
+                if (!isShadow && el.shadowRoot) {
+                    childNodes.push(...Array.from(el.shadowRoot.childNodes));
+                }
+                childNodes.push(...Array.from(node.childNodes));
+                if (tag === "iframe") {
+                    try {
+                        const d = el.contentDocument;
+                        if (d && d.body)
+                            childNodes.push(...Array.from(d.body.childNodes));
+                    }
+                    catch {
+                        /* cross-origin frame — handled by the >> drill instead */
+                    }
+                }
+                // --- Asymmetric scope: K-window siblings around the spine child ---
+                // Header rows (containing <th>) are always pinned so table column
+                // context survives even when data rows are pruned.
+                let siblingTotal = -1;
+                if (anchor && spine.has(el) && el !== anchor) {
+                    const elemKids = childNodes.filter((n) => n.nodeType === Node.ELEMENT_NODE);
+                    const pivot = elemKids.findIndex((k) => spine.has(k));
+                    if (pivot >= 0) {
+                        const keep = new Set();
+                        let pruned = false;
+                        elemKids.forEach((k, i) => {
+                            if (spine.has(k) ||
+                                (i >= pivot - K && i <= pivot + K) ||
+                                containsHeader(k))
+                                keep.add(k);
+                            else
+                                pruned = true;
+                        });
+                        if (pruned) {
+                            siblingTotal = elemKids.length;
+                            childNodes = childNodes.filter((n) => n.nodeType !== Node.ELEMENT_NODE ||
+                                keep.has(n));
+                        }
+                    }
+                }
+                // Generic wrappers with no semantic signal collapse to their
+                // children; transparent roots (body/html) emit children only.
+                // Neither emits a tag or consumes an fx-id index.
+                const collapses = COLLAPSIBLE.has(tag) && !hasSignal(el);
+                if (collapses || isTransparent(tag)) {
+                    return childNodes.map(renderNode).filter(Boolean).join("") || null;
+                }
+                // Reserve this element's fx-id BEFORE rendering children so the
+                // index reflects document order (parent indexed before its kids).
+                const isContainer = CONTAINER.has(tag);
+                const fxId = isContainer ? -1 : counter.v++;
+                const childHtml = childNodes.map(renderNode).filter(Boolean).join("");
+                // --- Build attributes ---
                 const attrs = [];
-                const preserved = [
-                    "id",
-                    "class",
-                    "data-testid",
-                    "name",
-                    "role",
-                    "src",
-                    "srcdoc",
-                ];
-                preserved.forEach((a) => {
+                if (fxId >= 0)
+                    attrs.push(`fx-id="${fxId}"`);
+                if (anchor && el === anchor) {
+                    const n = globalMatches(el);
+                    if (n > 1)
+                        attrs.push(`fx-global-matches="${n}"`);
+                }
+                if (siblingTotal > 0)
+                    attrs.push(`data-sibling-total="${siblingTotal}"`);
+                for (const a of PRESERVED) {
                     const v = el.getAttribute?.(a);
-                    if (v) {
-                        // שומרים מספיק מ-srcdoc כדי שה-AI יזהה מה יש בפנים
-                        const val = a === "srcdoc" ? v.substring(0, 200) : v;
-                        attrs.push(`${a}="${val}"`);
+                    if (v)
+                        attrs.push(`${a}="${a === "srcdoc" ? v.substring(0, 200) : v}"`);
+                }
+                // Image filename fallback: even without alt/title the basename of the
+                // src often carries intent (e.g. trash-can-icon.svg).
+                if (tag === "img") {
+                    const src = el.getAttribute("src");
+                    if (src) {
+                        const base = src
+                            .split("?")[0]
+                            .split("#")[0]
+                            .split("/")
+                            .filter(Boolean)
+                            .pop();
+                        if (base)
+                            attrs.push(`data-src-name="${base}"`);
                     }
-                });
-                attrs.push(`fx-id="${indexCounter++}"`);
-                // 4. איסוף ילדים (כולל Shadow DOM)
-                const childrenArr = [];
-                if (el instanceof HTMLElement && el.shadowRoot) {
-                    childrenArr.push(...Array.from(el.shadowRoot.childNodes));
-                }
-                childrenArr.push(...Array.from(node.childNodes));
-                // 5. עיבוד ילדים וטקסט פנימי
-                const childrenHtml = childrenArr
-                    .map(processNode)
-                    .filter(Boolean)
-                    .join("");
-                // אם אין ילדים אבל יש טקסט (כמו בכפתור), ניקח אותו
-                const innerContent = childrenHtml || node.textContent?.trim() || "";
-                const attrStr = attrs.length > 0 ? " " + attrs.join(" ") : "";
-                return `<${tag}${attrStr}>${innerContent}</${tag}>`;
+                }
+                const inner = childHtml ||
+                    (node.textContent ? truncate(node.textContent.trim()) : "");
+                const attrStr = attrs.length ? " " + attrs.join(" ") : "";
+                return `<${tag}${attrStr}>${inner}</${tag}>`;
             };
             const root = document.body || document.documentElement;
-            return processNode(root) || "";
-        });
+            let out = renderNode(root) || "";
+            // Char-budget hard cap (cheap token proxy) — degrade, never overflow.
+            if (out.length > budget)
+                out = out.slice(0, budget) + "<!--fx-truncated-->";
+            return out;
+        }, { selector, K: 3, maxText: 200, budget: 25000 });
         return result;
     }
     static getElementDNA = async (page, selector) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sela-core",
-  "version": "1.0.8",
+  "version": "1.0.9",
   "description": "AI self-healing Playwright wrapper - drop-in replacement for @playwright/test",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",