bee-ladybug 0.6.3 → 0.6.5

package/README.MD

@@ -1,10 +1,19 @@
 
 # BeeLadybug
+[![types](https://img.shields.io/npm/types/bee-ladybug)](https://www.npmjs.com/package/bee-ladybug)
+[![npm](https://img.shields.io/npm/v/bee-ladybug)](https://www.npmjs.com/package/bee-ladybug)
+[![download](https://img.shields.io/npm/dm/bee-ladybug)](https://www.npmjs.com/package/bee-ladybug)
+[![](https://data.jsdelivr.com/v1/package/npm/bee-ladybug/badge)](https://www.jsdelivr.com/package/npm/bee-ladybug)
+![licenza](https://img.shields.io/npm/l/bee-ladybug)
+[![Socket Badge](https://badge.socket.dev/npm/package/bee-ladybug/0.6.5)](https://badge.socket.dev/npm/package/bee-ladybug/0.6.5)
+[![size](https://img.shields.io/bundlephobia/minzip/bee-ladybug)](https://bundlephobia.com/package/bee-ladybug)
+[![Snyk](https://snyk.io/test/npm/bee-ladybug/badge.svg)](https://security.snyk.io/package/npm/bee-ladybug)
 
 <p align="center">
   <img src="https://beeenginejs.com/wp-content/uploads/2026/10/beeladybug-logo-animato-ezgif.com-effects.gif" alt="BeeEngine Logo" width="900" />
 </p>
 
+
 Universal telemetry and visual inspection overlay.
 
 BeeLadybug is **not** a Canvas widget. It is a small open-source debugger

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bee-ladybug",
-  "version": "0.6.3",
+  "version": "0.6.5",
   "description": "Universal telemetry and visual inspection overlay for Canvas, DOM, Python and AI flows.",
   "type": "module",
   "main": "src/index.js",

package/src/adapters/AntAdapter.js

@@ -38,6 +38,7 @@ export class AntAdapter {
         this.source = cfg.source;
 
         this.#attached = false;
+        this.#active = false;
         this.#observer = null;
         this.#counts = new WeakMap();
         this.#hot = [];
@@ -45,6 +46,8 @@ export class AntAdapter {
     }
 
     #attached;
+    /** False while the ANT button is off: setRoot() must not restart the observer then. */
+    #active;
     #observer;
     #counts;
     #hot;
@@ -53,17 +56,19 @@ export class AntAdapter {
     attach() {
         if (this.#attached) return this;
         this.#attached = true;
-        this.#enable();
+        this.#turnOn();
         this.core?.registerAdapter('ant', {
-            enable: () => this.#enable(),
+            enable: () => this.#turnOn(),
             disable: () => this.#disable(),
             label: 'ANT',
             snapshot: () => this.snapshot()
         });
-        this.core?.sendData('log', {
-            source: this.source,
-            message: 'AntAdapter attached. Watching DOM mutation rate.'
-        });
+        if (this.#observer) {
+            this.core?.sendData('log', {
+                source: this.source,
+                message: 'AntAdapter attached. Watching DOM mutation rate.'
+            });
+        }
         return this;
     }
 
@@ -75,6 +80,19 @@ export class AntAdapter {
         return this;
     }
 
+    /**
+     * Watch another root. Counters and hot rows restart; `null` stops watching.
+     * @param {ParentNode | null} root
+     */
+    setRoot(root) {
+        this.root = root;
+        if (!this.#attached) return this;
+        this.#reset();
+        if (!root || !this.#active) return this;
+        this.#warnNotWatching(this.#observe());
+        return this;
+    }
+
     /**
      * Nodes whose current window is still at or above the threshold.
      * Hidden boxes, the WordPress admin bar, and BeeLadybug chrome are skipped.
@@ -99,49 +117,83 @@ export class AntAdapter {
         return { name: 'ant', items };
     }
 
-    #enable() {
-        if (!this.#attached || this.#observer) return;
-        if (typeof MutationObserver === 'undefined' || !this.root) return;
+    #turnOn() {
+        if (!this.#attached) return;
+        this.#active = true;
+        this.#warnNotWatching(this.#observe());
+    }
+
+    #disable() {
+        this.#active = false;
+        this.#reset();
+    }
+
+    #reset() {
+        if (this.#observer) this.#observer.disconnect();
+        this.#observer = null;
+        this.#counts = new WeakMap();
+        this.#hot = [];
+    }
+
+    /** @returns {'' | 'no-root' | 'no-observer' | 'failed'} why nothing is watched, empty when it is */
+    #observe() {
+        if (this.#observer) return '';
+        if (!this.root) return 'no-root';
+        if (typeof MutationObserver === 'undefined') return 'no-observer';
         this.#counts = new WeakMap();
-        this.#observer = new MutationObserver(this.#onMutate);
+        const observer = new MutationObserver(this.#onMutate);
         try {
-            this.#observer.observe(this.root, {
+            observer.observe(this.root, {
                 childList: true,
                 subtree: true,
                 attributes: true,
                 characterData: true
             });
         } catch {
-            this.#observer.disconnect();
-            this.#observer = null;
+            observer.disconnect();
+            return 'failed';
         }
+        this.#observer = observer;
+        return '';
     }
 
-    #disable() {
-        if (this.#observer) this.#observer.disconnect();
-        this.#observer = null;
-        this.#counts = new WeakMap();
-        this.#hot = [];
+    #warnNotWatching(reason) {
+        if (!reason) return;
+        const messages = {
+            'no-root': 'no root: mutation rate is not watched. Pass { root } or call setRoot().',
+            'no-observer': 'MutationObserver is missing: mutation rate is not watched.',
+            failed: 'observe() failed: mutation rate is not watched.'
+        };
+        this.core?.sendData('warn', { source: this.source, message: messages[reason] });
     }
 
     #ingest(records) {
         if (!this.#attached || !this.core || !records?.length) return;
         const now = typeof performance !== 'undefined' ? performance.now() : Date.now();
+        this.#prune(now);
+        // One layout read per element per batch, however many records it produced.
+        const skipped = new Map();
         for (let i = 0; i < records.length; i++) {
-            const node = records[i]?.target;
-            if (!node || isBeeChrome(node)) continue;
+            const el = elementOf(records[i]?.target);
+            if (!el) continue;
+            let skip = skipped.get(el);
+            if (skip === undefined) {
+                skip = isBeeChrome(el) || isReportNoise(el);
+                skipped.set(el, skip);
+            }
+            if (skip) continue;
 
-            let slot = this.#counts.get(node);
+            let slot = this.#counts.get(el);
             if (!slot || now - slot.windowStart >= this.windowMs) {
                 slot = { count: 0, windowStart: now, warned: false };
-                this.#counts.set(node, slot);
+                this.#counts.set(el, slot);
             }
             slot.count += 1;
-            this.#track(node, slot);
+            this.#track(el, slot);
             if (slot.count < this.threshold || slot.warned) continue;
 
             slot.warned = true;
-            const selector = nodeSelector(node);
+            const selector = nodeSelector(el);
             this.core.sendData('warn', {
                 source: this.source,
                 message: `High Mutation Rate on ${selector}`,
@@ -150,21 +202,36 @@ export class AntAdapter {
         }
     }
 
-    #track(node, slot) {
-        const index = this.#hot.findIndex((row) => row.node === node);
+    #prune(now) {
+        this.#hot = this.#hot.filter((row) => now - row.windowStart < this.windowMs);
+    }
+
+    #track(el, slot) {
+        const index = this.#hot.findIndex((row) => row.node === el);
         if (slot.count < this.threshold) {
             if (index >= 0) this.#hot.splice(index, 1);
             return;
         }
         const row = {
-            node,
-            selector: nodeSelector(node),
+            node: el,
+            selector: nodeSelector(el),
             count: slot.count,
             windowStart: slot.windowStart
         };
         if (index >= 0) this.#hot[index] = row;
         else this.#hot.push(row);
-        if (this.#hot.length > MAX_HOT) this.#hot.splice(0, this.#hot.length - MAX_HOT);
+        while (this.#hot.length > MAX_HOT) this.#hot.splice(this.#lowestRow(), 1);
+    }
+
+    /** Fewest mutations first; on a tie the older window goes. */
+    #lowestRow() {
+        let worst = 0;
+        for (let i = 1; i < this.#hot.length; i++) {
+            const row = this.#hot[i];
+            const low = this.#hot[worst];
+            if (row.count < low.count || (row.count === low.count && row.windowStart < low.windowStart)) worst = i;
+        }
+        return worst;
     }
 }
 
@@ -173,15 +240,26 @@ function positive(value, fallback) {
     return Number.isFinite(n) && n > 0 ? n : fallback;
 }
 
+/** A text node counts on its parent element, so one element keeps one window. */
+function elementOf(node) {
+    if (!node) return null;
+    if (node.nodeType === 1) return node;
+    return node.parentElement || null;
+}
+
 function nodeSelector(node) {
-    const el = node && node.nodeType === 1 ? node : node?.parentElement;
+    const el = elementOf(node);
     if (!el || !el.tagName) return 'node';
-    if (el.id) return `#${el.id}`;
+    if (el.id) return `#${cssEscape(el.id)}`;
     const cls = el.classList && el.classList[0];
-    if (cls) return `.${cls}`;
+    if (cls) return `.${cssEscape(cls)}`;
     return el.tagName.toLowerCase();
 }
 
+function cssEscape(value) {
+    return String(value).replace(/[^\w-]/g, '\\$&');
+}
+
 function isBeeChrome(node) {
     let el = node && node.nodeType === 1 ? node : node?.parentElement;
     while (el) {
@@ -189,6 +267,7 @@ function isBeeChrome(node) {
         if (tag === 'BEE-LADYBUG-OVERLAY') return true;
         if (el.hasAttribute?.('data-bee-ladybug-dom')) return true;
         if (el.hasAttribute?.('data-bee-ladybug-canvas')) return true;
+        if (el.hasAttribute?.('data-bee-ladybug-css')) return true;
         el = el.parentElement;
     }
     return false;

package/src/adapters/CSSAdapter.js

@@ -61,9 +61,13 @@ export class CSSAdapter {
         this.#hoverBox = null;
         this.#pinBox = null;
         this.#observer = null;
+        this.#unsubscribe = null;
+        this.#hasPointer = false;
         this.#onMove = (event) => {
+            if (this.core && this.core.visible === false) return;
             this.#x = event.clientX;
             this.#y = event.clientY;
+            this.#hasPointer = true;
             this.#schedule();
         };
         this.#onKey = (event) => this.#handleKey(event);
@@ -71,7 +75,7 @@ export class CSSAdapter {
         this.#onMutate = (records) => {
             if (!records.some(touchesSheet)) return;
             this.#sheetsDirty = true;
-            this.#schedule();
+            if (this.#hasPointer) this.#schedule();
         };
     }
 
@@ -92,6 +96,9 @@ export class CSSAdapter {
     #hoverBox;
     #pinBox;
     #observer;
+    #unsubscribe;
+    /** True after the first mousemove: before that (x, y) is not a real pointer. */
+    #hasPointer;
     #onMove;
     #onKey;
     #onScroll;
@@ -104,6 +111,9 @@ export class CSSAdapter {
     attach() {
         if (this.#attached) return this;
         this.#attached = true;
+        if (this.core && typeof this.core.subscribe === 'function') {
+            this.#unsubscribe = this.core.subscribe((packet) => this.#onCore(packet));
+        }
         this.core?.registerAdapter('css', {
             label: this.label,
             hotkey: this.hotkey,
@@ -128,10 +138,21 @@ export class CSSAdapter {
         if (!this.#attached) return this;
         this.#disable();
         this.#attached = false;
+        if (this.#unsubscribe) this.#unsubscribe();
+        this.#unsubscribe = null;
         this.core?.unregisterAdapter('css');
         return this;
     }
 
+    #onCore(packet) {
+        if (packet.type !== 'sys' || packet.payload?.op !== 'visibility') return;
+        this.#placeBoxes();
+    }
+
+    #boxesVisible() {
+        return !(this.core && this.core.visible === false);
+    }
+
     /** Page scan. Click a row to outline one element of that group. */
     scan() {
         if (!this.#active || typeof document === 'undefined') return this;
@@ -141,15 +162,15 @@ export class CSSAdapter {
         const rows = [];
         for (let i = 0; i < nodes.length; i++) {
             const el = nodes[i];
-            if (!el || isBeeChrome(el) || isSkippedTag(el)) continue;
+            if (!el || isBeeChrome(el) || isSkippedTag(el) || isReportNoise(el)) continue;
             const measured = measureViewportOverflow(el);
             if (measured) overflow.push(measured);
             const findings = [];
             pushNegativeMargins(el, findings);
             pushInvisible(el, findings);
-            pushBlockers(el, findings);
+            pushBlockers(el, findings, true);
             pushImage(el, findings);
-            pushStacking(el, findings);
+            pushStacking(el, findings, true);
             pushImportant(el, this.#rules, findings);
             for (let j = 0; j < findings.length; j++) {
                 rows.push({ el, selector: cssPath(el), ...findings[j] });
@@ -245,7 +266,9 @@ export class CSSAdapter {
         for (let i = 0; i < rows.length; i++) {
             const row = rows[i];
             if (describeCause(row.kind, row.selector)) {
-                causes = addCause(causes, { kind: row.kind, path: row.selector, el: row.el }, MAX_SNAPSHOT);
+                // No cap here: MAX_SNAPSHOT applies after the severity sort, so an info row
+                // can never push a real error out.
+                causes = addCause(causes, { kind: row.kind, path: row.selector, el: row.el }, Infinity);
             } else {
                 plain.push(row);
             }
@@ -319,6 +342,7 @@ export class CSSAdapter {
     #disable() {
         if (!this.#active) return;
         this.#active = false;
+        this.#hasPointer = false;
         if (typeof window !== 'undefined') {
             window.removeEventListener('mousemove', this.#onMove, true);
             window.removeEventListener('keydown', this.#onKey);
@@ -340,11 +364,16 @@ export class CSSAdapter {
         this.core?.publishDetail([]);
         this.core?.publishIssues([]);
         this.core?.sendData('state', { source: this.source, key: 'css.hunt', value: 'off' });
+        this.core?.sendData('state', { source: this.source, key: 'css.target', value: '—' });
+        this.core?.sendData('state', { source: this.source, key: 'css.hits', value: '0' });
+        this.core?.sendData('state', { source: this.source, key: 'css.pin', value: 'off' });
         this.core?.sendData('log', { source: this.source, message: 'CSS hunt off.' });
     }
 
     #handleKey(event) {
         if (!this.#active || event.repeat) return;
+        if (event.ctrlKey || event.metaKey || event.altKey) return;
+        if (this.core && this.core.visible === false) return;
         if (isTypingTarget(event.target)) return;
         if (event.code === this.pinKey) {
             event.preventDefault();
@@ -377,22 +406,23 @@ export class CSSAdapter {
 
     #inspect(x, y) {
         const el = pickElement(x, y);
-        placeBox(this.#hoverBox, el);
+        placeBox(this.#hoverBox, el, this.#boxesVisible());
         if (this.#panelLock) return;
         if (el === this.#lastEl) return;
         this.#lastEl = el;
         if (!el) {
             this.core?.publishDetail([]);
             this.core?.sendData('state', { source: this.source, key: 'css.target', value: '—' });
+            this.core?.sendData('state', { source: this.source, key: 'css.hits', value: '0' });
             return;
         }
         const findings = [];
         pushImportant(el, this.#rules, findings);
         pushOverflow(el, findings);
         pushInvisible(el, findings);
-        pushBlockers(el, findings);
+        pushBlockers(el, findings, true);
         pushImage(el, findings);
-        pushStacking(el, findings);
+        pushStacking(el, findings, true);
         const path = cssPath(el);
         this.core?.sendData('state', { source: this.source, key: 'css.target', value: path });
         this.core?.sendData('state', {
@@ -419,7 +449,7 @@ export class CSSAdapter {
         if (this.#panelLock) {
             this.#panelLock = false;
             this.#pinned = null;
-            placeBox(this.#pinBox, null);
+            placeBox(this.#pinBox, null, this.#boxesVisible());
             this.core?.sendData('state', { source: this.source, key: 'css.pin', value: 'off' });
             this.core?.sendData('log', { source: this.source, message: 'CSS pin off.' });
             this.#lastEl = null;
@@ -504,15 +534,16 @@ export class CSSAdapter {
 
     #pin(el) {
         this.#pinned = el;
-        placeBox(this.#pinBox, el);
+        placeBox(this.#pinBox, el, this.#boxesVisible());
         if (el && typeof el.scrollIntoView === 'function') {
             el.scrollIntoView({ block: 'center', inline: 'nearest', behavior: 'smooth' });
         }
     }
 
     #placeBoxes() {
-        placeBox(this.#hoverBox, this.#lastEl);
-        placeBox(this.#pinBox, this.#pinned);
+        const visible = this.#boxesVisible();
+        placeBox(this.#hoverBox, this.#lastEl, visible);
+        placeBox(this.#pinBox, this.#pinned, visible);
     }
 
     #mountBoxes() {
@@ -538,6 +569,8 @@ function collectImportantRules() {
     const sheets = document.styleSheets;
     for (let i = 0; i < sheets.length; i++) {
         const sheet = sheets[i];
+        if (sheet.disabled === true) continue;
+        if (sheet.media && sheet.media.mediaText && !mediaMatches(sheet.media.mediaText)) continue;
         let list = null;
         try {
             list = sheet.cssRules;
@@ -550,21 +583,21 @@ function collectImportantRules() {
     return { rules, unreadable };
 }
 
+function mediaMatches(mediaText) {
+    try {
+        return typeof matchMedia === 'function' ? matchMedia(mediaText).matches : true;
+    } catch {
+        return true;
+    }
+}
+
 function walkRules(list, source, into) {
     if (!list) return;
     for (let i = 0; i < list.length; i++) {
         const rule = list[i];
         if (!rule) continue;
         if (rule.type === 4 && rule.media) {
-            let active = true;
-            try {
-                active = typeof matchMedia === 'function'
-                    ? matchMedia(rule.media.mediaText).matches
-                    : true;
-            } catch {
-                active = true;
-            }
-            if (active) walkRules(rule.cssRules, source, into);
+            if (mediaMatches(rule.media.mediaText)) walkRules(rule.cssRules, source, into);
             continue;
         }
         if (rule.type === 1 && rule.selectorText && rule.style) {
@@ -745,7 +778,9 @@ function pushInvisible(el, findings) {
         findings.push(issue('invisible text (opacity 0)', ISSUE_RANK.invisible, 30));
     }
     const color = parseColor(style.color);
-    if (!color || color.a === 0) {
+    // Unknown syntax (oklch, lab, color(), color-mix): nothing to compare, nothing to report.
+    if (!color) return;
+    if (color.a === 0) {
         findings.push(issue('invisible text (transparent color)', ISSUE_RANK.invisible, 30));
         return;
     }
@@ -1096,7 +1131,7 @@ function pickElement(x, y) {
     const stack = document.elementsFromPoint(x, y);
     for (let i = 0; i < stack.length; i++) {
         const el = stack[i];
-        if (!el || isBeeChrome(el)) continue;
+        if (!el || isBeeChrome(el) || isReportNoise(el)) continue;
         if (el === document.documentElement || el === document.body) continue;
         return el;
     }
@@ -1154,12 +1189,16 @@ function hasOwnText(el) {
 function cssPath(el) {
     if (!el || !el.tagName) return 'node';
     const tag = el.tagName.toLowerCase();
-    if (el.id) return `${tag}#${el.id}`;
+    if (el.id) return `${tag}#${cssEscape(el.id)}`;
     const classes = el.classList ? [...el.classList].slice(0, 2) : [];
-    if (classes.length) return `${tag}.${classes.join('.')}`;
+    if (classes.length) return `${tag}.${classes.map(cssEscape).join('.')}`;
     return tag;
 }
 
+function cssEscape(value) {
+    return String(value).replace(/[^\w-]/g, '\\$&');
+}
+
 function isSkippedTag(el) {
     const tag = el.tagName;
     return tag === 'SCRIPT' || tag === 'STYLE' || tag === 'LINK' || tag === 'META';
@@ -1179,7 +1218,10 @@ function touchesSheet(record) {
         const name = record.target?.nodeName;
         return name === 'STYLE' || name === 'LINK';
     }
-    const nodes = [record.target];
+    // Only what was added or removed: the target's whole subtree always holds some <style> or <link>.
+    // A <style> that receives new text is the one target worth checking, and that check is O(1).
+    if (record.target?.nodeName === 'STYLE') return true;
+    const nodes = [];
     if (record.addedNodes) {
         for (let i = 0; i < record.addedNodes.length; i++) nodes.push(record.addedNodes[i]);
     }
@@ -1220,9 +1262,9 @@ function makeBox(kind, border, fill) {
     return node;
 }
 
-function placeBox(node, el) {
+function placeBox(node, el, visible = true) {
     if (!node) return;
-    if (!el || typeof el.getBoundingClientRect !== 'function' || isBeeChrome(el)) {
+    if (visible === false || !el || typeof el.getBoundingClientRect !== 'function' || isBeeChrome(el)) {
         node.style.display = 'none';
         return;
     }

package/src/adapters/WebDOMAdapter.js

@@ -520,6 +520,7 @@ function isBeeChrome(node) {
         if (tag === 'BEE-LADYBUG-OVERLAY') return true;
         if (el.hasAttribute?.('data-bee-ladybug-dom')) return true;
         if (el.hasAttribute?.('data-bee-ladybug-canvas')) return true;
+        if (el.hasAttribute?.('data-bee-ladybug-css')) return true;
         el = el.parentElement;
     }
     return false;

package/src/core/BeeLadybugCore.js

@@ -10,7 +10,7 @@ import { UIOverlay } from './UIOverlay.js';
 import { buildAssistantSnapshot, normalizeAssistant } from './AiAssistant.js';
 import { exportReport as writeReport } from './ReportExporter.js';
 
-export const BEE_LADYBUG_VERSION = '0.6.3';
+export const BEE_LADYBUG_VERSION = '0.6.5';
 
 export const CORE_DEFAULTS = Object.freeze({
     toggleKey: 'F2',

package/src/index.d.ts

@@ -424,6 +424,7 @@ export class AntAdapter {
     constructor(core: BeeLadybugCore, options?: AntAdapterOptions);
     attach(): this;
     detach(): this;
+    setRoot(root: ParentNode | null): this;
     snapshot(): ReportSnapshot | null;
 }