RemoteFunctions.js

// this is a single file sent to browser preview. keep this light. add features as extensions
// Please do not add any license header in this file as it will end up in distribution bin as is.
/**
 * RemoteFunctions define the functions to be executed in the browser. This
 * modules should define a single function that returns an object of all
 * exported functions.
 */
// eslint-disable-next-line no-unused-vars
function RemoteFunctions(config = {}) {
    const GLOBALS = {
        // given to internal elements like info box, tool box, image gallery and all other phcode internal elements
        // to distinguish between phoenix internal vs user created elements
        PHCODE_INTERNAL_ATTR: "data-phcode-internal-c15r5a9",
        DATA_BRACKETS_ID_ATTR: "data-brackets-id", // data attribute used to track elements for live preview operations
        LP_REF_ATTR: "data-phcode-lp-ref", // identity of a script-added element, stamped only when it is selected
        HIGHLIGHT_CLASSNAME: "__brackets-ld-highlight" // CSS class name used for highlighting elements in live preview
    };

    // this is for bidirectional communication between phoenix and live preview
    const PhoenixComm = window._Brackets_LiveDev_PhoenixComm;
    PhoenixComm && PhoenixComm.registerLpFn("PH_Hello", function(param) {
        // this is just a test function here to check if live preview. fn call is working correctly.
        console.log("Hello World", param);
    });
    const MessageBroker = window._Brackets_MessageBroker; // to be used by plugins.

    const SHARED_STATE = {
        __description: "Use this to keep shared state for Live Preview Edit instead of window.*",
        _suppressDOMEditDismissal: false,
        _suppressDOMEditDismissalTimeout: null,
        _boxModelHighlightHidden: false
    };

    let _hoverHighlight;
    let _clickHighlight;
    let _cssSelectorHighlight; // temporary highlight for CSS selector matches in edit mode
    let _hoverLockTimer = null;
    let _cssSelectorHighlightTimer = null;
    let _lastHoverTarget = null; // tracks the element currently under the mouse (for same-element skip)
    let _pendingHoverRAF = null; // pending requestAnimationFrame ID for hover updates

    // this will store the element that was clicked previously (before the new click)
    // we need this so that we can remove click styling from the previous element when a new element is clicked
    let previouslySelectedElement = null;
    let _sourcelessObserver = null;
    let _sourcelessCheckTimer = null;
    let _sourcelessPath = null;
    let _sourcelessTag = null;
    let _sourcelessClass = null;
    const SOURCELESS_RECOVER_DELAY_MS = 60;
    let _selectedFromEditor = false;
    // the element selected by name (layers panel row), not by pointer
    let _namedSelection = null;
    // Expose the currently selected element globally for external access
    window.__current_ph_lp_selected = null;

    const COLORS = {
        highlightPadding: "rgba(147, 196, 125, 0.55)",
        highlightMargin: "rgba(246, 178, 107, 0.66)",
        outlineEditable: "#4285F4",
        outlineNonEditable: "#3C3F41"
    };

    // the following fucntions can be in the handler and live preview will call those functions when the below
    // events happen
    const allowedHandlerFns = [
        "dismiss", // when handler gets this event, it should dismiss all ui it renders in the live preview
        "createToolBox",
        "createInfoBox",
        "showHoverBox",
        "createMoreOptionsDropdown",
        // render an icon or html when the selected element toolbox appears in edit mode.
        "renderToolBoxItem",
        "redraw",
        "onElementSelected", // an item is selected in live preview
        "onElementCleanup",
        "onNonEditableElementClick", // called when user clicks on a non-editable element
        "handleConfigChange",
        // below  function gets called to render the dropdown when user clicks on the ... menu in the tool box,
        // the handler should retrun html tor ender the dropdown item.
        "renderDropdownItems",
        // called when an item is selected from the more options dropdown
        "handleDropdownClick",
        "updateContent", // in-place content refresh for control box etc. after drag
        // a DOM edit changed the selected element's attributes or rebuilt its node —
        // refresh shown UI in place; must never resurrect dismissed UI
        "onSelectedElementMutated",
        "reRegisterEventHandlers",
        "handleClick", // handle click on an icon in the tool box.
        // when escape key is presses in the editor, we may need to dismiss the live edit boxes.
        "handleEscapePress",
        // interaction blocks acts as 'kill switch' to block all kinds of click handlers
        // this is done so that links or buttons doesn't perform their natural operation in edit mode
        "registerInteractionBlocker", // to block
        "unregisterInteractionBlocker", // to unblock
        "udpateHotCornerState" // to update the hot corner button when state changes
    ];

    const _toolHandlers = new Map();
    function registerToolHandler(handlerName, handler) {
        if(_toolHandlers.get(handlerName)) {
            console.error(`lp: Tool handler '${handlerName}' already registered. Ignoring new registration`);
            return;
        }
        if (!handler || typeof handler !== "object") {
            console.error(`lp: Tool handler '${handlerName}' value is invalid ${JSON.stringify(handler)}.`);
            return;
        }
        handler.handlerName = handlerName;
        for (const key of Object.keys(handler)) {
            if (key !== "handlerName" && !allowedHandlerFns.includes(key)) {
                console.warn(`lp: Tool handler '${handlerName}' has unknown property '${key}'`,
                    `should be one of ${allowedHandlerFns.join(",")}`);
            }
        }
        _toolHandlers.set(handlerName, handler);
    }
    function getToolHandler(handlerName) {
        return _toolHandlers.get(handlerName);
    }
    function getAllToolHandlers() {
        return Array.from(_toolHandlers.values());
    }

    /**
     * check if an element is inspectable.
     * inspectable elements are those which doesn't have GLOBALS.DATA_BRACKETS_ID_ATTR ('data-brackets-id'),
     * this normally happens when content is DOM content is inserted by some scripting language
     *
     * Elements opted out via `phcode-no-lp-edit` (cascades to descendants) or
     * `phcode-no-lp-edit-this` (this element only) are also non-inspectable so
     * every downstream tool inherits the opt-out automatically.
     *
     * @param {DOMElement} element
     * @param {boolean} [onlyHighlight=false] - If true, bypasses the mode check
     */
    function isElementInspectable(element, onlyHighlight = false) {
        if(config.mode !== 'edit' && !onlyHighlight) {
            return false;
        }

        if(element && // element should exist
            (!isBodyElement(element) || _isNamedSelection(element)) && // body only when selected by name
            element.tagName.toLowerCase() !== "html" && // shouldn't be the HTML tag
            // this attribute is used by phoenix internal elements
            !element.closest(`[${GLOBALS.PHCODE_INTERNAL_ATTR}]`) &&
            !_isInsideHeadTag(element) && // shouldn't be inside the head tag like meta tags and all
            !_isEditOptedOut(element)) {
            return true;
        }
        return false;
    }

    // The body is never selected by pointer (blank clicks deselect, hover stays quiet),
    // only by name from the layers panel or the caret, and then without the structural tools.
    function isBodyElement(element) {
        return !!(element && element.tagName && element.tagName.toLowerCase() === "body");
    }

    // a named selection lifts the `phcode-no-lp-edit` opt-out and the body block, both pointer-only guards
    function _isNamedSelection(element) {
        return !!element && element === _namedSelection;
    }

    /**
     * `phcode-no-lp-edit` cascades to descendants, `phcode-no-lp-edit-this` covers
     * the one element.
     */
    function _isEditOptedOut(element) {
        if (_isNamedSelection(element)) {
            return false;
        }
        return !!(element.closest('.phcode-no-lp-edit') ||
            (element.classList && element.classList.contains('phcode-no-lp-edit-this')));
    }

    /**
     * This is a checker function for editable elements, it makes sure that the element satisfies all the required check
     * - When onlyHighlight is false → config.mode must be 'edit'
     * - When onlyHighlight is true → config.mode can be any mode (doesn't matter)
     * @param {DOMElement} element
     * @param {boolean} [onlyHighlight=false] - If true, bypasses the mode check
     * @returns {boolean} - True if the element is editable else false
     */
    function isElementEditable(element, onlyHighlight = false) {
        // for an element to be editable it should satisfy all inspectable checks and should also have data-brackets-id
        return isElementInspectable(element, onlyHighlight) && element.hasAttribute(GLOBALS.DATA_BRACKETS_ID_ATTR);
    }

    // no data-brackets-id means a script added the element, so there is no HTML source for it
    function isSourceless(element) {
        return !!element && !element.hasAttribute(GLOBALS.DATA_BRACKETS_ID_ATTR);
    }

    let _lpRefCounter = 0;
    const LP_REF_PREFIX = "j";
    const RE_NUMERIC_ID = /^\d+$/;

    function getElementRef(element) {
        if (!element || element.nodeType !== Node.ELEMENT_NODE) {
            return null;
        }
        const tagId = element.getAttribute(GLOBALS.DATA_BRACKETS_ID_ATTR);
        if (tagId) {
            return tagId;
        }
        let ref = element.getAttribute(GLOBALS.LP_REF_ATTR);
        if (!ref) {
            ref = LP_REF_PREFIX + (++_lpRefCounter);
            element.setAttribute(GLOBALS.LP_REF_ATTR, ref);
        }
        return ref;
    }

    function getElementByRef(ref) {
        if (ref === null || ref === undefined || ref === "") {
            return null;
        }
        const text = String(ref);
        const attr = RE_NUMERIC_ID.test(text) ? GLOBALS.DATA_BRACKETS_ID_ATTR : GLOBALS.LP_REF_ATTR;
        return window.document.querySelector("[" + attr + '="' + text + '"]');
    }

    /**
     * this function calc the screen offset of an element
     *
     * @param {DOMElement} element
     * @returns {{left: number, top: number}}
     */
    function screenOffset(element) {
        const elemBounds = element.getBoundingClientRect();
        const body = window.document.body;
        let offsetTop;
        let offsetLeft;

        if (window.getComputedStyle(body).position === "static") {
            offsetLeft = elemBounds.left + window.pageXOffset;
            offsetTop = elemBounds.top + window.pageYOffset;
        } else {
            const bodyBounds = body.getBoundingClientRect();
            offsetLeft = elemBounds.left - bodyBounds.left;
            offsetTop = elemBounds.top - bodyBounds.top;
        }
        return { left: offsetLeft, top: offsetTop };
    }

    const LivePreviewView = {
        registerToolHandler: registerToolHandler,
        getToolHandler: getToolHandler,
        getAllToolHandlers: getAllToolHandlers,
        isElementEditable: isElementEditable,
        isElementInspectable: isElementInspectable,
        isBodyElement: isBodyElement,
        isSourceless: isSourceless,
        getElementRef: getElementRef,
        getElementByRef: getElementByRef,
        isElementVisible: isElementVisible,
        screenOffset: screenOffset,
        selectElement: selectElement,
        isSelectedFromEditor: function () { return _selectedFromEditor; },
        isNamedSelection: _isNamedSelection,
        toMatchableSelector: toMatchableSelector,
        sendSelectionToEditor: sendSelectionToEditor,
        brieflyDisableHoverListeners: brieflyDisableHoverListeners,
        handleElementClick: handleElementClick,
        cleanupPreviousElementState: cleanupPreviousElementState,
        disableHoverListeners: disableHoverListeners,
        enableHoverListeners: enableHoverListeners,
        redrawHighlights: redrawHighlights,
        redrawEverything: redrawEverything,
        getTreePath: _getTreePath,
        getElementByTreePath: _getElementByTreePath,
        getSourceChildren: _instrumentedChildren
    };

    /**
     * @type {DOMEditHandler}
     */
    var _editHandler;

    // the below code comment is replaced by added scripts for extensibility
    // DONT_STRIP_MINIFY:REPLACE_WITH_ADDED_REMOTE_CONSTANT_SCRIPTS

    // helper function to check if an element is inside the HEAD tag
    // we need this because we don't wanna trigger the element highlights on head tag and its children,
    // except for <style> tags which should be allowed
    function _isInsideHeadTag(element) {
        let parent = element;
        while (parent && parent !== window.document) {
            if (parent.tagName.toLowerCase() === "head") {
                // allow <style> tags inside <head>
                return element.tagName.toLowerCase() !== "style";
            }
            parent = parent.parentElement;
        }
        return false;
    }

    // set an event on a element
    function _trigger(element, name, value, autoRemove) {
        var key = "data-ld-" + name;
        if (value !== undefined && value !== null) {
            element.setAttribute(key, value);
            if (autoRemove) {
                window.setTimeout(element.removeAttribute.bind(element, key));
            }
        } else {
            element.removeAttribute(key);
        }
    }

    // Checks if the element is in Viewport in the client browser
    function isInViewport(element) {
        var rect = element.getBoundingClientRect();
        var html = window.document.documentElement;
        return (
            rect.top >= 0 &&
            rect.bottom <= (window.innerHeight || html.clientHeight)
        );
    }

    // Checks if an element is actually visible to the user (not hidden, collapsed, or off-screen)
    function isElementVisible(element) {
        // Check if element has zero dimensions (indicates it's hidden or collapsed)
        const rect = element.getBoundingClientRect();
        if (rect.width === 0 && rect.height === 0) {
            return false;
        }

        // Check computed styles for visibility
        const computedStyle = window.getComputedStyle(element);
        if (computedStyle.display === 'none' ||
            computedStyle.visibility === 'hidden' ||
            computedStyle.opacity === '0') {
            return false;
        }

        // Check if any parent element is hidden
        let parent = element.parentElement;
        while (parent && parent !== document.body) {
            const parentStyle = window.getComputedStyle(parent);
            if (parentStyle.display === 'none' ||
                parentStyle.visibility === 'hidden') {
                return false;
            }
            parent = parent.parentElement;
        }

        return true;
    }

    // returns the distance from the top of the closest relatively positioned parent element
    function getDocumentOffsetTop(element) {
        return element.offsetTop + (element.offsetParent ? getDocumentOffsetTop(element.offsetParent) : 0);
    }

    // Shadow DOM host for highlight overlays — isolates our UI from user page CSS.
    let _highlightShadowHost = null;
    let _highlightShadowRoot = null;

    const HIGHLIGHT_CSS = `:host {
        all: initial !important;
    }

    .overlay-container {
        position: absolute !important;
        z-index: 2147483645 !important;
        margin: 0 !important;
        padding: 0 !important;
        border: none !important;
        pointer-events: none !important;
        box-sizing: border-box !important;
    }

    .rect {
        position: absolute !important;
    }

    .overlay-container.hidden {
        display: none !important;
    }

    .outline {
        position: absolute !important;
        box-sizing: border-box !important;
        pointer-events: none !important;
    }`;

    function _ensureHighlightShadowRoot() {
        if (_highlightShadowRoot) {
            return _highlightShadowRoot;
        }
        _highlightShadowHost = window.document.createElement("div");
        _highlightShadowHost.className = GLOBALS.HIGHLIGHT_CLASSNAME;
        _highlightShadowHost.setAttribute(GLOBALS.PHCODE_INTERNAL_ATTR, "true");
        _highlightShadowRoot = _highlightShadowHost.attachShadow({ mode: "open" });
        _highlightShadowRoot.innerHTML = `<style>${HIGHLIGHT_CSS}</style>`;
        window.document.body.appendChild(_highlightShadowHost);
        return _highlightShadowRoot;
    }

    // Overlay pool — overlays are created once and reused across highlights.
    // When released, they stay in the shadow DOM (hidden) ready for instant reuse.
    // This eliminates all DOM creation/destruction from the highlight hot paths.
    const _overlayPool = [];

    function _createOverlayStructure() {
        const div = window.document.createElement("div");
        div.className = "overlay-container hidden";

        function createRect() {
            const r = window.document.createElement("div");
            r.className = "rect";
            return r;
        }

        const padTop = createRect(), padBottom = createRect(),
            padLeft = createRect(), padRight = createRect();
        const marTop = createRect(), marBottom = createRect(),
            marLeft = createRect(), marRight = createRect();
        const outline = window.document.createElement("div");
        outline.className = "outline";

        div.appendChild(padTop);
        div.appendChild(padBottom);
        div.appendChild(padLeft);
        div.appendChild(padRight);
        div.appendChild(marTop);
        div.appendChild(marBottom);
        div.appendChild(marLeft);
        div.appendChild(marRight);
        div.appendChild(outline);

        // Cache child references for O(1) access during updates
        div._refs = {
            padTop, padBottom, padLeft, padRight,
            marTop, marBottom, marLeft, marRight,
            outline
        };

        _ensureHighlightShadowRoot().appendChild(div);
        return div;
    }

    function _getOverlay() {
        return _overlayPool.length > 0 ? _overlayPool.pop() : _createOverlayStructure();
    }

    function _releaseOverlay(overlay) {
        overlay.classList.add('hidden');
        overlay.trackingElement = null;
        _overlayPool.push(overlay);
    }

    // Everything an overlay needs read off the page. Split from the painting
    // below so a batch of overlays can read first and write after: interleaving
    // the two forces a layout per element.
    // What screenOffset() needs off the body, read once for a whole batch
    // instead of once per element.
    function _bodyOffsetContext() {
        const body = window.document.body;
        if (window.getComputedStyle(body).position === "static") {
            return { isStatic: true, x: window.pageXOffset, y: window.pageYOffset };
        }
        const bodyBounds = body.getBoundingClientRect();
        return { isStatic: false, x: bodyBounds.left, y: bodyBounds.top };
    }

    function _offsetFromBounds(bounds, bodyOffset) {
        if (bodyOffset.isStatic) {
            return { left: bounds.left + bodyOffset.x, top: bounds.top + bodyOffset.y };
        }
        return { left: bounds.left - bodyOffset.x, top: bounds.top - bodyOffset.y };
    }

    function _measureOverlay(element, bodyOffset) {
        const bounds = element.getBoundingClientRect();
        if (bounds.width === 0 && bounds.height === 0) {
            return null;
        }
        const cs = window.getComputedStyle(element);
        return {
            bounds: bounds,
            scroll: _offsetFromBounds(bounds, bodyOffset || _bodyOffsetContext()),
            bt: parseFloat(cs.borderTopWidth) || 0,
            br: parseFloat(cs.borderRightWidth) || 0,
            bb: parseFloat(cs.borderBottomWidth) || 0,
            bl: parseFloat(cs.borderLeftWidth) || 0,
            pt: parseFloat(cs.paddingTop) || 0,
            pr: parseFloat(cs.paddingRight) || 0,
            pb: parseFloat(cs.paddingBottom) || 0,
            pl: parseFloat(cs.paddingLeft) || 0,
            mt: parseFloat(cs.marginTop) || 0,
            mr: parseFloat(cs.marginRight) || 0,
            mb: parseFloat(cs.marginBottom) || 0,
            ml: parseFloat(cs.marginLeft) || 0
        };
    }

    function _measureAll(elements) {
        const bodyOffset = _bodyOffsetContext();
        const measured = [];
        for (let i = 0; i < elements.length; i++) {
            measured.push(_measureOverlay(elements[i], bodyOffset));
        }
        return measured;
    }

    // Update an existing overlay's position, dimensions, and colors to match the target element.
    // No DOM elements are created or destroyed — only style properties are updated.
    function _paintOverlay(overlay, element, measured) {
        if (!measured) {
            overlay.classList.add('hidden');
            return;
        }

        const bounds = measured.bounds;

        // Parse box model values (getComputedStyle always resolves to px)
        const bt = measured.bt, br = measured.br, bb = measured.bb, bl = measured.bl;
        const pt = measured.pt, pr = measured.pr, pb = measured.pb, pl = measured.pl;
        const mt = measured.mt, mr = measured.mr, mb = measured.mb, ml = measured.ml;

        // Compute the 4 absolute boxes exactly like dev tools:
        // getBoundingClientRect() always returns the border box regardless of box-sizing.
        const scroll = measured.scroll;
        const borderBox = {
            left: scroll.left,
            top: scroll.top,
            width: bounds.width,
            height: bounds.height
        };
        const paddingBox = {
            left: borderBox.left + bl,
            top: borderBox.top + bt,
            width: borderBox.width - bl - br,
            height: borderBox.height - bt - bb
        };
        const contentBox = {
            left: paddingBox.left + pl,
            top: paddingBox.top + pt,
            width: paddingBox.width - pl - pr,
            height: paddingBox.height - pt - pb
        };
        const marginBox = {
            left: borderBox.left - ml,
            top: borderBox.top - mt,
            width: borderBox.width + ml + mr,
            height: borderBox.height + mt + mb
        };

        // Update container position
        overlay.trackingElement = element;
        overlay.style.left = marginBox.left + "px";
        overlay.style.top = marginBox.top + "px";
        overlay.style.width = marginBox.width + "px";
        overlay.style.height = marginBox.height + "px";
        overlay.classList.remove('hidden');

        const refs = overlay._refs;
        const mLeft = marginBox.left;

        // Update a rect's position, size, and color in place
        function setRect(rect, left, top, width, height, color) {
            const s = rect.style;
            s.left = (left - mLeft) + "px";
            s.top = (top - marginBox.top) + "px";
            s.width = Math.max(0, width) + "px";
            s.height = Math.max(0, height) + "px";
            s.backgroundColor = color;
        }

        // Padding region. Rects stay in place when hidden, only their fill goes away,
        // so nothing has to be rebuilt when they come back.
        const boxModelHidden = SHARED_STATE._boxModelHighlightHidden;
        const padColor = boxModelHidden ? "transparent" : COLORS.highlightPadding;
        setRect(refs.padTop, paddingBox.left, paddingBox.top, paddingBox.width, pt, padColor);
        setRect(refs.padBottom, paddingBox.left, contentBox.top + contentBox.height, paddingBox.width, pb, padColor);
        setRect(refs.padLeft, paddingBox.left, contentBox.top, pl, contentBox.height, padColor);
        setRect(refs.padRight, contentBox.left + contentBox.width, contentBox.top, pr, contentBox.height, padColor);

        // Margin region
        const margColor = boxModelHidden ? "transparent" : COLORS.highlightMargin;
        setRect(refs.marTop, marginBox.left, marginBox.top, marginBox.width, mt, margColor);
        setRect(refs.marBottom, marginBox.left, borderBox.top + borderBox.height, marginBox.width, mb, margColor);
        setRect(refs.marLeft, marginBox.left, borderBox.top, ml, borderBox.height, margColor);
        setRect(refs.marRight, borderBox.left + borderBox.width, borderBox.top, mr, borderBox.height, margColor);

        // Outline
        const isEditable = element.hasAttribute(GLOBALS.DATA_BRACKETS_ID_ATTR);
        const outlineColor = isEditable ? COLORS.outlineEditable : COLORS.outlineNonEditable;
        const outlineStyle = refs.outline.style;
        outlineStyle.left = (borderBox.left - mLeft) + "px";
        outlineStyle.top = (borderBox.top - marginBox.top) + "px";
        outlineStyle.width = borderBox.width + "px";
        outlineStyle.height = borderBox.height + "px";
        outlineStyle.border = `1px solid ${outlineColor}`;
    }

    function _updateOverlay(overlay, element) {
        _paintOverlay(overlay, element, _measureOverlay(element));
    }

    function Highlight(trigger) {
        this.trigger = !!trigger;
        this.elements = [];
        this.selector = "";
        this._overlays = [];
    }

    Highlight.prototype = {
        add: function (element) {
            if (this.elements.includes(element) || element === window.document) {
                return;
            }
            if (this.trigger) {
                _trigger(element, "highlight", 1);
            }

            this.elements.push(element);
            const overlay = _getOverlay();
            this._overlays.push(overlay);
            _updateOverlay(overlay, element);
        },

        addAll: function (elements) {
            const seen = new Set(this.elements);
            const fresh = [];
            for (let i = 0; i < elements.length; i++) {
                const element = elements[i];
                if (element !== window.document && !seen.has(element)) {
                    seen.add(element);
                    fresh.push(element);
                }
            }
            const measured = _measureAll(fresh);
            for (let i = 0; i < fresh.length; i++) {
                if (this.trigger) {
                    _trigger(fresh[i], "highlight", 1);
                }
                this.elements.push(fresh[i]);
                const overlay = _getOverlay();
                this._overlays.push(overlay);
                _paintOverlay(overlay, fresh[i], measured[i]);
            }
        },

        clear: function () {
            this._overlays.forEach(function (overlay) {
                _releaseOverlay(overlay);
            });
            this._overlays = [];

            if (this.trigger) {
                this.elements.forEach(function (el) {
                    _trigger(el, "highlight", 0);
                });
            }

            this.elements = [];
            // Reset the cached selector so that redraw() uses the elements
            // array instead of re-querying the DOM with a stale selector.
            // Without this, a selector like [data-brackets-id='3'] persists
            // after the element is replaced (e.g. tag name change assigns a
            // new ID), causing redraw() to find zero matches and release
            // all overlays — making the highlight vanish.
            this.selector = "";
        },

        redraw: function () {
            const elements = this.selector
                ? Array.from(window.document.querySelectorAll(this.selector))
                : this.elements.slice();

            // Adjust overlay count to match element count
            while (this._overlays.length > elements.length) {
                _releaseOverlay(this._overlays.pop());
            }
            while (this._overlays.length < elements.length) {
                this._overlays.push(_getOverlay());
            }

            this.elements = elements;

            // Update all overlays in place — no DOM creation or destruction
            const measured = _measureAll(elements);
            for (let i = 0; i < elements.length; i++) {
                _paintOverlay(this._overlays[i], elements[i], measured[i]);
            }
        }
    };

    // helper function to get the current elements highlight mode
    // this is as per user settings (either click or hover)
    function getHighlightMode() {
        return config.elemHighlights ? config.elemHighlights.toLowerCase() : "hover";
    }

    // helper function to check if highlights should show on hover
    function shouldShowHighlightOnHover() {
        return getHighlightMode() !== "click";
    }

    /**
     * Applies the current hover state in a single batched DOM update.
     * Called once per animation frame via requestAnimationFrame.
     * _lastHoverTarget holds the element to highlight (or null to clear).
     */
    function _applyHoverState() {
        _pendingHoverRAF = null;

        if (!_hoverHighlight || !shouldShowHighlightOnHover()) {
            return;
        }

        _hoverHighlight.clear();
        const hoverBoxHandler = LivePreviewView.getToolHandler("HoverBox");
        if (hoverBoxHandler) {
            hoverBoxHandler.dismiss();
        }

        const element = _lastHoverTarget;

        if (element && (element !== previouslySelectedElement || _selectedFromEditor)) {
            _hoverHighlight.add(element);
            if (hoverBoxHandler) {
                hoverBoxHandler.showHoverBox(element);
            }
        }
    }

    /**
     * Schedules a hover state update for the next animation frame.
     * Multiple calls within one frame collapse into a single DOM update.
     */
    function _scheduleHoverUpdate() {
        if (!_pendingHoverRAF) {
            _pendingHoverRAF = requestAnimationFrame(_applyHoverState);
        }
    }

    function onElementHover(event) {
        // don't want highlighting and stuff when auto scrolling or when dragging (svgs)
        // for dragging normal html elements its already taken care of...so we just add svg drag checking
        if (SHARED_STATE.isAutoScrolling || SHARED_STATE._isDraggingSVG) {
            return;
        }
        const element = event.target;

        if (element === _lastHoverTarget) {
            return;
        }
        if(isBodyElement(element) || !LivePreviewView.isElementInspectable(element) ||
                element.nodeType !== Node.ELEMENT_NODE) {
            return;
        }
        _lastHoverTarget = element;

        // if _hoverHighlight is uninitialized, initialize it
        if (!_hoverHighlight && shouldShowHighlightOnHover()) {
            _hoverHighlight = new Highlight(true);
        }

        if (_hoverHighlight && shouldShowHighlightOnHover()) {
            _scheduleHoverUpdate();
        }
    }

    function _clearHoverState() {
        if (SHARED_STATE.isAutoScrolling) {
            return;
        }
        if (_hoverHighlight && shouldShowHighlightOnHover()) {
            _lastHoverTarget = null;
            _scheduleHoverUpdate();
        }
    }

    function onElementHoverOut(event) {
        const element = event.target;
        // Use isElementInspectable (not isElementEditable) so that JS-rendered
        // elements also get their hover highlight and hover box properly dismissed.
        if(LivePreviewView.isElementInspectable(element) && element.nodeType === Node.ELEMENT_NODE) {
            _clearHoverState();
        }
    }

    // for popped out window: the in-panel iframe case is forwarded parent-side via _LD.clearHoverState().
    function onDocumentMouseLeave() {
        _clearHoverState();
    }

    function scrollElementToViewPort(element) {
        if (!element) {
            return;
        }

        // Check if element is in viewport, if not scroll to it
        if (!isInViewport(element)) {
            let top = getDocumentOffsetTop(element);
            if (top) {
                top -= (window.innerHeight / 2);
                window.scrollTo(0, top);
            }
        }
    }

    /**
     * this function is responsible to select an element in the live preview
     * @param {Element} element - The DOM element to select
     * @param {boolean} [fromEditor] - If true, this is an editor-cursor-driven selection;
     *   only lightweight highlights (outline, margin/padding overlay) are shown, not interactive
     *   UI like the control box or the styles bar.
     * @param {boolean} [byName] - Selected by name (a layers panel row), so the edit
     *   opt-out and the body block don't apply while it stays selected.
     */
    function selectElement(element, fromEditor, byName) {
        // When a cursor-based highlight re-selects the already-selected element,
        // just refresh the highlight overlay without dismissing existing UI panels
        // (control box, editor box, element-info). This prevents cursor activity
        // after a source edit (e.g., tag name change) from tearing down the
        // element properties panel and losing its state.
        if (fromEditor && element === previouslySelectedElement) {
            if (!_clickHighlight) {
                _clickHighlight = new Highlight();
            }
            _clickHighlight.clear();
            _clickHighlight.add(element);
            return;
        }

        dismissUIAndCleanupState();
        // set after the dismissal, which clears the previous selection's exemption
        _namedSelection = byName ? element : null;
        // this should also be there when users are in highlight mode
        scrollElementToViewPort(element);

        if(!LivePreviewView.isElementInspectable(element, true)) {
            return false;
        }

        // Only invoke tool handlers for user-initiated clicks in the live preview,
        // not for editor cursor movements which should only show lightweight highlights
        if (!fromEditor) {
            // when user clicks on a non-editable element
            if (!element.hasAttribute(GLOBALS.DATA_BRACKETS_ID_ATTR)) {
                getAllToolHandlers().forEach(handler => {
                    if (handler.onNonEditableElementClick) {
                        handler.onNonEditableElementClick(element);
                    }
                });
            }

            // make sure that the element is actually visible to the user
            if (isElementVisible(element)) {
                // Notify handlers about element selection
                getAllToolHandlers().forEach(handler => {
                    if (handler.onElementSelected) {
                        handler.onElementSelected(element);
                    }
                });
            }
        }

        if (!_clickHighlight) {
            _clickHighlight = new Highlight();
        }
        _clickHighlight.clear();
        _clickHighlight.add(element);

        previouslySelectedElement = element;
        _selectedFromEditor = fromEditor || false;
        window.__current_ph_lp_selected = element;
        if (isSourceless(element)) {
            _watchSourcelessSelection(element);
        }
    }

    function _elementIndexPath(element) {
        const path = [];
        let el = element;
        while (el && el !== window.document.body) {
            const parent = el.parentElement;
            if (!parent) {
                return null;
            }
            path.unshift(Array.prototype.indexOf.call(parent.children, el));
            el = parent;
        }
        return el === window.document.body ? path : null;
    }

    function _elementAtIndexPath(path) {
        let el = window.document.body;
        for (let i = 0; i < path.length && el; i++) {
            el = el.children[path[i]];
        }
        return el || null;
    }

    // a re-render replaces a script-added node, so re-select the same tag in the same place or dismiss
    function _watchSourcelessSelection(element) {
        _unwatchSourcelessSelection();
        _sourcelessPath = _elementIndexPath(element);
        if (!_sourcelessPath) {
            return;
        }
        _sourcelessTag = element.tagName;
        _sourcelessClass = typeof element.className === "string" ? element.className : "";
        _sourcelessObserver = new MutationObserver(function () {
            if (_sourcelessCheckTimer || !previouslySelectedElement || previouslySelectedElement.isConnected) {
                return;
            }
            _sourcelessCheckTimer = setTimeout(_recoverSourcelessSelection, SOURCELESS_RECOVER_DELAY_MS);
        });
        _sourcelessObserver.observe(window.document.body, { childList: true, subtree: true });
    }

    function _unwatchSourcelessSelection() {
        if (_sourcelessObserver) {
            _sourcelessObserver.disconnect();
            _sourcelessObserver = null;
        }
        if (_sourcelessCheckTimer) {
            clearTimeout(_sourcelessCheckTimer);
            _sourcelessCheckTimer = null;
        }
        _sourcelessPath = null;
    }

    function _recoverSourcelessSelection() {
        _sourcelessCheckTimer = null;
        const old = previouslySelectedElement;
        if (!old || old.isConnected || !_sourcelessPath) {
            return;
        }
        const fresh = _elementAtIndexPath(_sourcelessPath);
        const className = fresh && typeof fresh.className === "string" ? fresh.className : "";
        if (fresh && fresh.tagName === _sourcelessTag && className === _sourcelessClass &&
                isSourceless(fresh) && isElementInspectable(fresh, true) && isElementVisible(fresh)) {
            const fromEditor = _selectedFromEditor;
            selectElement(fresh, fromEditor);
        } else {
            dismissUIAndCleanupState();
        }
    }

    function disableHoverListeners() {
        window.document.removeEventListener("mouseover", onElementHover);
        window.document.removeEventListener("mousemove", onElementHover);
        window.document.removeEventListener("mouseout", onElementHoverOut);
        window.document.documentElement.removeEventListener("mouseleave", onDocumentMouseLeave);
        // Cancel any pending rAF hover update so stale callbacks don't fire
        if (_pendingHoverRAF) {
            cancelAnimationFrame(_pendingHoverRAF);
            _pendingHoverRAF = null;
        }
        _lastHoverTarget = null;
    }

    function enableHoverListeners() {
        // don't enable hover listeners if user is currently editing an element
        // this was added to fix a specific bug:
        // lets say user double clicked an element: so as soon as the first click is made,
        // 'breiflyDisableHoverListeners' is called which has a timer to re-enable hover listeners,
        // because of which even during editing the hover listeners were working
        if (SHARED_STATE._currentlyEditingElement) {
            return;
        }
        if (config.mode === 'edit' && shouldShowHighlightOnHover()) {
            disableHoverListeners();
            window.document.addEventListener("mouseover", onElementHover);
            window.document.addEventListener("mousemove", onElementHover);
            window.document.addEventListener("mouseout", onElementHoverOut);
            window.document.documentElement.addEventListener("mouseleave", onDocumentMouseLeave);
        }
    }

    /**
     * this function disables hover listeners for 800ms to prevent ui conclicts
     * Used when user performs click actions to avoid UI box conflicts
     */
    function brieflyDisableHoverListeners() {
        if (_hoverLockTimer) {
            clearTimeout(_hoverLockTimer);
        }

        disableHoverListeners();
        _hoverLockTimer = setTimeout(() => {
            enableHoverListeners();
            _hoverLockTimer = null;
        }, 800);
    }

    /**
     * this function is called when user clicks on an element in the LP when in edit mode
     *
     * @param {HTMLElement} element - The clicked element
     * @param {Event} event - The click event
     */