sela-core 0.1.0-alpha.1

package/dist/types/index.d.ts

@@ -0,0 +1,95 @@
+export interface AncestorNode {
+    tag: string;
+    id: string | null;
+    classes: string[];
+    /** "{tag}#{id}[{classes_sorted_asc}]" - stable fingerprint for drift comparison */
+    fingerprint: string;
+}
+export type GhostCondition = "G1_DISPLAY_NONE" | "G2_VISIBILITY_HIDDEN" | "G3_OPACITY_ZERO" | "G4_POINTER_EVENTS_NONE" | "G5_ZERO_AREA" | "G6_CONTENT_VISIBILITY_HIDDEN";
+export interface VisibilityInfo {
+    isGhost: boolean;
+    ghostReason: GhostCondition | null;
+    isOccluded: boolean;
+    /** Computed opacity at capture time (0–1). Ghost threshold: < 0.05. */
+    opacity: number;
+}
+export interface AnchorInfo {
+    /** Resolved via: aria-labelledby → aria-label → label[for] → implicit label → preceding sibling */
+    closestLabel: string | null;
+    /** Longest unique sibling cell text when element lives in a table row; null otherwise */
+    rowAnchor: string | null;
+    /** Up to 5 direct-sibling texts (< 100 chars each). Stored for inspection; not scored in v2. */
+    neighborTexts: string[];
+}
+/**
+ * Disk format for element snapshots.
+ *
+ * v1 snapshots (no schemaVersion field) carry only the original fields.
+ * v2 snapshots (schemaVersion: 2) add ancestry, visibility, anchors, and
+ * isInShadowDom.  v1 snapshots are migrated to v2 on load by SnapshotService.
+ */
+export interface ElementSnapshot {
+    tagName: string;
+    id: string | null;
+    text: string | null;
+    classes: string[];
+    attributes: Record<string, string>;
+    role: string | null;
+    parentContext: string;
+    timestamp: string;
+    rect?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    schemaVersion?: 1 | 2;
+    ancestry?: AncestorNode[];
+    visibility?: VisibilityInfo;
+    anchors?: AnchorInfo;
+    isInShadowDom?: boolean;
+}
+/** Narrowed type asserting that all v2 fields are present. */
+export type ElementSnapshotV2 = ElementSnapshot & {
+    schemaVersion: 2;
+    ancestry: AncestorNode[];
+    visibility: VisibilityInfo;
+    anchors: AnchorInfo;
+    isInShadowDom: boolean;
+};
+export declare function isSnapshotV2(s: ElementSnapshot): s is ElementSnapshotV2;
+export interface FixRequest {
+    targetIntent: string;
+    failedSelector: string;
+    previousState: object;
+    currentDom: string;
+}
+export interface FixResponse {
+    status: "FIXED" | "NOT_FOUND";
+    new_selector: string | null;
+    confidence: number;
+    explanation: string;
+}
+export interface ElementDNA {
+    tagName: string;
+    text: string;
+    attributes: Record<string, string>;
+    styles: {
+        backgroundColor: string;
+        color: string;
+        display: string;
+        visibility: string;
+    };
+    rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    hierarchy: {
+        parentTag: string;
+        parentClass: string;
+        neighborTexts: string[];
+    };
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"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"}

package/dist/types/index.js

@@ -0,0 +1,7 @@
+"use strict";
+// ── DNA v2 Sub-types ─────────────────────────────────────────────────────────
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSnapshotV2 = isSnapshotV2;
+function isSnapshotV2(s) {
+    return s.schemaVersion === 2 && Array.isArray(s.ancestry);
+}

package/dist/utils/DOMUtils.d.ts

@@ -0,0 +1,49 @@
+import { Page } from "@playwright/test";
+import { ElementDNA } from "../types";
+export declare class DOMUtils {
+    /**
+     * Sanitizes a Playwright selector (which may contain `>>`) into a CSS-safe
+     * selector by extracting only the last segment. Returns the last meaningful
+     * CSS part so querySelector can be used inside the correct context.
+     */
+    static sanitizeSelector(selector: string): string;
+    /**
+     * Given a Playwright `>>` selector, returns each segment in order.
+     * e.g. "#my-iframe >> #shadow-host >> #btn"
+     *   → ["#my-iframe", "#shadow-host", "#btn"]
+     */
+    static parseSegments(selector: string): string[];
+    static getNeighborhoodDom(page: Page, fullSelector: string): Promise<{
+        dom: string;
+        successfulPath: string[];
+    }>;
+    /**
+     * When a selector has multiple ">>" segments, the first segments are
+     * typically iframe selectors. This helper drills into the correct frame
+     * before running the DOM extraction.
+     */
+    private static _getNeighborhoodFromFrame;
+    /**
+     * 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>;
+}
+//# sourceMappingURL=DOMUtils.d.ts.map

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

@@ -0,0 +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;AAGtC,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

@@ -0,0 +1,466 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DOMUtils = void 0;
+const logger_1 = require("./logger");
+class DOMUtils {
+    /**
+     * Sanitizes a Playwright selector (which may contain `>>`) into a CSS-safe
+     * selector by extracting only the last segment. Returns the last meaningful
+     * CSS part so querySelector can be used inside the correct context.
+     */
+    static sanitizeSelector(selector) {
+        const parts = selector.split(">>").map((s) => s.trim());
+        return parts[parts.length - 1];
+    }
+    /**
+     * Given a Playwright `>>` selector, returns each segment in order.
+     * e.g. "#my-iframe >> #shadow-host >> #btn"
+     *   → ["#my-iframe", "#shadow-host", "#btn"]
+     */
+    static parseSegments(selector) {
+        return selector.split(">>").map((s) => s.trim());
+    }
+    // src/utils/DOMUtils.ts (חלק רלוונטי)
+    // בתוך DOMUtils.ts
+    static async getNeighborhoodDom(page, fullSelector) {
+        // וודא שה-Return Type מעודכן כאן!
+        const segments = fullSelector.split(" >> ").map((s) => s.trim());
+        // כאן קוראים לפונקציה הפרטית שכתבנו קודם
+        const result = await this._getNeighborhoodFromFrame(page, segments);
+        // השגיאה שהצגת (Property length does not exist) קרתה כאן כנראה בלוג או בבדיקה
+        if (!result.dom || result.dom.length === 0) {
+            logger_1.logger.warn("No DOM content extracted");
+        }
+        return result; // מחזירים את האובייקט המלא { dom, successfulPath }
+    }
+    /**
+     * When a selector has multiple ">>" segments, the first segments are
+     * typically iframe selectors. This helper drills into the correct frame
+     * before running the DOM extraction.
+     */
+    static async _getNeighborhoodFromFrame(page, segments) {
+        const targetSelector = segments[segments.length - 1];
+        let currentContext = page;
+        const successfulPath = [];
+        try {
+            // עוברים על כל הפריימים בשרשרת
+            for (let i = 0; i < segments.length - 1; i++) {
+                const selector = segments[i];
+                logger_1.logger.debug(`Attempting to enter frame: ${selector}`);
+                let frameHandle = await currentContext
+                    .locator(selector)
+                    .elementHandle({ timeout: 2000 })
+                    .catch(() => null);
+                if (!frameHandle) {
+                    logger_1.logger.debug(`Frame ${selector} not found. Stopping drill at: ${successfulPath.join(" >> ") || "root"}`);
+                    break; // עוצרים ומחלצים מאיפה שהצלחנו להגיע
+                }
+                const frame = await frameHandle.contentFrame();
+                if (frame) {
+                    currentContext = frame;
+                    successfulPath.push(selector); // שומרים את ה-Breadcrumb
+                    logger_1.logger.debug(`Successfully entered context: ${selector}`);
+                }
+                else {
+                    break;
+                }
+            }
+            const dom = await DOMUtils._evaluateNeighborhood(currentContext, targetSelector);
+            return { dom, successfulPath };
+        }
+        catch (e) {
+            logger_1.logger.debug(`DOM extraction error: ${e.message}`);
+            return {
+                dom: await DOMUtils._evaluateNeighborhood(page, targetSelector),
+                successfulPath: [],
+            };
+        }
+    }
+    /**
+     * 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) {
+        logger_1.logger.debug(`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 t = node.textContent ? node.textContent.trim() : "";
+                    return t ? truncate(t) : null;
+                }
+                const isShadow = typeof ShadowRoot !== "undefined" && node instanceof ShadowRoot;
+                if (node.nodeType !== Node.ELEMENT_NODE && !isShadow)
+                    return null;
+                const el = isShadow
+                    ? node.host
+                    : node;
+                const tag = isShadow ? "shadow-root" : el.tagName.toLowerCase();
+                if (SKIP.has(tag))
+                    return null;
+                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 = [];
+                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)
+                        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}"`);
+                    }
+                }
+                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;
+            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) => {
+        return await page
+            .locator(selector)
+            .first()
+            .evaluate((el) => {
+            const rect = el.getBoundingClientRect();
+            const style = window.getComputedStyle(el);
+            const neighbors = Array.from(el.parentElement?.children || [])
+                .filter((child) => child !== el)
+                .map((child) => child.innerText?.substring(0, 20))
+                .filter(Boolean);
+            return {
+                tagName: el.tagName,
+                text: el.innerText,
+                attributes: Object.fromEntries(Array.from(el.attributes).map((a) => [a.name, a.value])),
+                styles: {
+                    backgroundColor: style.backgroundColor,
+                    color: style.color,
+                    display: style.display,
+                    visibility: style.visibility,
+                },
+                rect: {
+                    x: rect.x,
+                    y: rect.y,
+                    width: rect.width,
+                    height: rect.height,
+                },
+                hierarchy: {
+                    parentTag: el.parentElement?.tagName || "",
+                    parentClass: el.parentElement?.className || "",
+                    neighborTexts: neighbors,
+                },
+            };
+        });
+    };
+}
+exports.DOMUtils = DOMUtils;

package/dist/utils/FileLock.d.ts

@@ -0,0 +1,44 @@
+export interface FileLockOptions {
+    /** Backoff delays (ms) between async acquire attempts. */
+    delaysMs?: number[];
+    /** Busy-wait delays (ms) between sync acquire attempts. */
+    syncDelaysMs?: number[];
+    /**
+     * If the lock dir's mtime is older than this many ms, treat it as
+     * abandoned (the holder crashed without releasing) and reclaim it.
+     * 0 / undefined = never reclaim — prefer skipping a write over risking a
+     * double-writer. New callers that own their lock namespace should opt in.
+     */
+    staleMs?: number;
+    logger?: {
+        warn: (m: string) => void;
+    };
+}
+export declare class FileLock {
+    private readonly lockDir;
+    private readonly opts;
+    constructor(lockDir: string, opts?: FileLockOptions);
+    private warn;
+    /** Ensure the lock dir's PARENT exists (never the lock dir itself — that
+     *  would defeat the EEXIST mutex). */
+    private ensureParent;
+    private reclaimIfStale;
+    /** One attempt, no wait. True iff this call now holds the lock. */
+    tryAcquire(): boolean;
+    /** Async acquire with exponential backoff. */
+    acquire(): Promise<boolean>;
+    release(): void;
+    /**
+     * Run `fn` while holding the lock. Returns `fn`'s result, or `undefined`
+     * (and warns) when the lock could not be acquired within the backoff
+     * window. Mirrors the cache contract: a contended write is skipped, never
+     * thrown — the lock guards an optimisation/idempotent write, not a
+     * correctness invariant the caller cannot recover from.
+     */
+    withLock<T>(fn: () => T | Promise<T>): Promise<T | undefined>;
+    /** Synchronous variant — busy-waits between attempts. */
+    withLockSync<T>(fn: () => T): T | undefined;
+}
+/** Derive the conventional lock-dir path for a guarded file. */
+export declare function lockDirFor(filePath: string): string;
+//# sourceMappingURL=FileLock.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"FileLock.d.ts","sourceRoot":"","sources":["../../src/utils/FileLock.ts"],"names":[],"mappings":"AAmBA,MAAM,WAAW,eAAe;IAC9B,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,2DAA2D;IAC3D,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;KAAE,CAAC;CACxC;AAKD,qBAAa,QAAQ;IAEjB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,IAAI;gBADJ,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,eAAoB;IAG7C,OAAO,CAAC,IAAI;IAIZ;0CACsC;IACtC,OAAO,CAAC,YAAY;IAOpB,OAAO,CAAC,cAAc;IAkBtB,mEAAmE;IACnE,UAAU,IAAI,OAAO;IAyBrB,8CAA8C;IACxC,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC;IAUjC,OAAO,IAAI,IAAI;IAQf;;;;;;OAMG;IACG,QAAQ,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAYnE,yDAAyD;IACzD,YAAY,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,GAAG,SAAS;CAgB5C;AAED,gEAAgE;AAChE,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEnD"}