bee-ladybug 0.5.3 → 0.6.0

package/README.MD

@@ -2,7 +2,7 @@
 # BeeLadybug
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/antonioprosperi2-svg/BeeLadybug-universal/main/docs/logo.jpg" alt="BeeLadybug" width="720">
+  <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.
@@ -133,12 +133,26 @@ bee.subscribe((packet) => {
 | `F2` | mostra / nascondi overlay (e hitbox canvas) |
 | `F3` | slow-motion del tempo fittizio (`0.25x` / `1x`) |
 | `F4` | freeze / run del tempo fittizio |
+| `F8` | scarica il report HTML |
 | `F6` | CSS hunt, se `CSSAdapter` è attaccato |
 | `P` | blocca il pannello CSS sull'elemento corrente, solo con la hunt accesa |
 | `S` | scansione CSS, solo con la hunt accesa |
 
 Niente `F12`, niente tilde: sui layout italiani la tilde non è un tasto unico.
 
+## Export
+
+`F8`, il pulsante **F8 EXPORT** nel piede dell'overlay, o `exportReport()` scaricano `report-AAAAMMGG-HHMM.html`. Il file raccoglie log, serie e una sezione per ogni adapter attaccato. `json` e `csv` usano gli stessi dati.
+
+```js
+import { exportReport } from './src/index.js';
+
+exportReport(bee, { format: 'html' });
+bee.exportReport('json');
+```
+
+Con `ui: false`, o senza `document`, la chiamata restituisce la stringa o l'oggetto e non scarica nulla.
+
 ## CanvasAdapter
 
 ```js
@@ -199,6 +213,7 @@ css.attach();
 - overflow del viewport e margini negativi
 - testo trasparente, `opacity: 0`, o colore uguale allo sfondo
 - chi intercetta il click al centro, inclusi `::before` / `::after` fissi su `html` / `body`
+- un antenato che crea uno stacking context (`transform`, `opacity` sotto 1, `filter`, oppure `position` non static con `z-index`). I figli si raggruppano sulla causa: `div.hero creates stacking context (transform) - z-index of 3 children is trapped`. `will-change: transform` o `opacity` è una riga grigia, con la nota sullo `z-index` sulla stessa riga
 - `<img>` con rapporto del file diverso di oltre il 5% dal riquadro disegnato (`getBoundingClientRect`), solo se `object-fit` calcolato è `fill` (il default)
 
 `S` con la hunt accesa percorre la pagina. L'overflow resta solo sull'elemento che lo causa: un antenato si salta se un discendente sfora della stessa quantità (±2px), oppure se la larghezza del box ci sta nel viewport e a uscire è un figlio. Righe uguali (stesso selettore e stesso problema) diventano una sola, con il conteggio (`article overflows viewport ×4`). L'ordine è: causa di overflow, click bloccato, testo invisibile, immagine distorta, `!important`. Un click sulla riga disegna il contorno rosso. `P` ferma il pannello sull'elemento corrente. **Issues** raggruppa per causa: `body::after blocks clicks on 10 elements` è una riga rossa, e il click la apre sull'elenco degli elementi. In cima alla sezione, la legenda dice rosso = bug e grigio = info. Un foglio illeggibile è una riga grigia, una per foglio, e non entra tra i bug. L'overlay resta alto al massimo metà schermo, scorre al suo interno, e le sezioni Status, Issues, Inspect ed Events si chiudono. In console un elemento pulito non viene scritto, e con la hunt accesa restano fuori anche `hover` e `mutate attr` del DOM, a meno che `F3` SLOW sia acceso. Ogni problema CSS viene scritto una sola volta per elemento ogni 5 secondi. I fogli di stile restano in cache finché un `MutationObserver` non vede un cambio a `<style>` o `<link>`. Hover è limitato a un frame.
@@ -349,6 +364,7 @@ const bee = new BeeLadybugCore({
   toggleKey: 'F2',
   slowKey: 'F3',
   freezeKey: 'F4',
+  exportKey: 'F8',
   slowScale: 0.25,
   maxLogs: 250,
   historySize: 120,
@@ -367,6 +383,7 @@ bee.getHud();
 bee.show(); bee.hide(); bee.toggle();
 bee.freeze(); bee.unfreeze(); bee.toggleFreeze();
 bee.applySlowMo(); bee.restoreRealtime();
+bee.exportReport('html');
 bee.registerAssistant({ name: 'mock', complete: async ({ snapshot }) => 'ok' });
 bee.setActiveAssistant('mock');
 await bee.ask('why fps drop?');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bee-ladybug",
-  "version": "0.5.3",
+  "version": "0.6.0",
   "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

@@ -2,6 +2,7 @@
  * AntAdapter — DOM mutation rate tracker.
  *
  * Independent MutationObserver. Can sit on the same root as WebDOMAdapter.
+ * `snapshot()` lists nodes still over the mutation threshold.
  * The core must never import this file.
  *
  * @example
@@ -9,6 +10,10 @@
  * ant.attach();
  */
 
+import { isReportNoise } from '../core/ReportExporter.js';
+
+const MAX_HOT = 40;
+
 export const ANT_ADAPTER_DEFAULTS = Object.freeze({
     threshold: 30,
     windowMs: 1000,
@@ -35,12 +40,14 @@ export class AntAdapter {
         this.#attached = false;
         this.#observer = null;
         this.#counts = new WeakMap();
+        this.#hot = [];
         this.#onMutate = (records) => this.#ingest(records);
     }
 
     #attached;
     #observer;
     #counts;
+    #hot;
     #onMutate;
 
     attach() {
@@ -50,7 +57,8 @@ export class AntAdapter {
         this.core?.registerAdapter('ant', {
             enable: () => this.#enable(),
             disable: () => this.#disable(),
-            label: 'ANT'
+            label: 'ANT',
+            snapshot: () => this.snapshot()
         });
         this.core?.sendData('log', {
             source: this.source,
@@ -67,6 +75,30 @@ export class AntAdapter {
         return this;
     }
 
+    /**
+     * Nodes whose current window is still at or above the threshold.
+     * Hidden boxes, the WordPress admin bar, and BeeLadybug chrome are skipped.
+     * @returns {{ name: string, items: Array<{ severity: string, selector: string, rule: string, value: string, source: string }> } | null}
+     */
+    snapshot() {
+        if (!this.#attached) return null;
+        const now = typeof performance !== 'undefined' ? performance.now() : Date.now();
+        const items = [];
+        for (let i = 0; i < this.#hot.length && items.length < MAX_HOT; i++) {
+            const row = this.#hot[i];
+            if (!row || now - row.windowStart >= this.windowMs) continue;
+            if (isBeeChrome(row.node) || isReportNoise(row.node)) continue;
+            items.push({
+                severity: 'warn',
+                selector: row.selector,
+                rule: 'mutations',
+                value: `${row.count}/${this.windowMs}ms`,
+                source: this.source
+            });
+        }
+        return { name: 'ant', items };
+    }
+
     #enable() {
         if (!this.#attached || this.#observer) return;
         if (typeof MutationObserver === 'undefined' || !this.root) return;
@@ -89,6 +121,7 @@ export class AntAdapter {
         if (this.#observer) this.#observer.disconnect();
         this.#observer = null;
         this.#counts = new WeakMap();
+        this.#hot = [];
     }
 
     #ingest(records) {
@@ -104,6 +137,7 @@ export class AntAdapter {
                 this.#counts.set(node, slot);
             }
             slot.count += 1;
+            this.#track(node, slot);
             if (slot.count < this.threshold || slot.warned) continue;
 
             slot.warned = true;
@@ -115,6 +149,23 @@ export class AntAdapter {
             });
         }
     }
+
+    #track(node, slot) {
+        const index = this.#hot.findIndex((row) => row.node === node);
+        if (slot.count < this.threshold) {
+            if (index >= 0) this.#hot.splice(index, 1);
+            return;
+        }
+        const row = {
+            node,
+            selector: nodeSelector(node),
+            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);
+    }
 }
 
 function positive(value, fallback) {

package/src/adapters/CSSAdapter.js

@@ -4,6 +4,7 @@
  * Hover an element to list !important hits, viewport overflow, negative
  * margins, invisible text, click blockers and stretched images. The core
  * only receives packets and detail rows; it does not parse CSS.
+ * `snapshot()` repeats that scan for the report while the hunt is off.
  *
  * @example
  * const css = new CSSAdapter(core);
@@ -11,6 +12,10 @@
  * // F6 toggles hunt. S scans the page while hunt is on.
  */
 
+import { isReportNoise } from '../core/ReportExporter.js';
+
+const MAX_SNAPSHOT = 80;
+
 export const CSS_ADAPTER_DEFAULTS = Object.freeze({
     source: 'css',
     hotkey: 'F6',
@@ -104,7 +109,8 @@ export class CSSAdapter {
             hotkey: this.hotkey,
             enabled: false,
             enable: () => this.#enable(),
-            disable: () => this.#disable()
+            disable: () => this.#disable(),
+            snapshot: () => this.snapshot()
         });
         this.core?.sendData('log', {
             source: this.source,
@@ -143,6 +149,7 @@ export class CSSAdapter {
             pushInvisible(el, findings);
             pushBlockers(el, findings);
             pushImage(el, findings);
+            pushStacking(el, findings);
             pushImportant(el, this.#rules, findings);
             for (let j = 0; j < findings.length; j++) {
                 rows.push({ el, selector: cssPath(el), ...findings[j] });
@@ -190,6 +197,98 @@ export class CSSAdapter {
         return this;
     }
 
+    /**
+     * Full hunt scan for the report. Hunt can stay off: nothing is logged,
+     * pinned, or published. Hidden boxes, WordPress admin, and BeeLadybug
+     * chrome are skipped.
+     * @returns {{ name: string, items: Array<{ severity: string, selector: string, rule: string, value: string, source: string }> } | null}
+     */
+    snapshot() {
+        if (!this.#attached) return null;
+        if (typeof document === 'undefined' || !document.body) return { name: 'css', items: [] };
+
+        const built = collectImportantRules();
+        const nodes = document.body.querySelectorAll('*');
+        const overflow = [];
+        const rows = [];
+        for (let i = 0; i < nodes.length; i++) {
+            const el = nodes[i];
+            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);
+            pushImage(el, findings);
+            pushStacking(el, findings);
+            pushImportant(el, built.rules, findings);
+            for (let j = 0; j < findings.length; j++) {
+                rows.push({ el, selector: cssPath(el), ...findings[j] });
+            }
+        }
+        const kept = keepOverflowCauses(overflow);
+        for (let i = 0; i < kept.length; i++) {
+            const cause = kept[i];
+            rows.push({
+                el: cause.el,
+                selector: cssPath(cause.el),
+                kind: 'overflows viewport',
+                rank: 0,
+                level: 'error',
+                score: cause.score
+            });
+        }
+
+        let causes = [];
+        const plain = [];
+        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);
+            } else {
+                plain.push(row);
+            }
+        }
+
+        const items = [];
+        for (let i = 0; i < causes.length; i++) {
+            const entry = causes[i];
+            items.push({
+                severity: reportSeverity(entry.level),
+                selector: entry.cause,
+                rule: causeRule(entry.type),
+                value: formatCause(entry),
+                source: this.source
+            });
+        }
+        const groups = groupIssues(plain);
+        for (let i = 0; i < groups.length; i++) {
+            const group = groups[i];
+            const count = group.count > 1 ? ` ×${group.count}` : '';
+            items.push({
+                severity: reportSeverity(group.level),
+                selector: group.selector,
+                rule: plainRule(group.kind),
+                value: `${group.kind}${count}`,
+                source: this.source
+            });
+        }
+        for (let i = 0; i < built.unreadable.length; i++) {
+            const label = built.unreadable[i];
+            items.push({
+                severity: 'ok',
+                selector: label,
+                rule: 'unreadable sheet',
+                value: label,
+                source: this.source
+            });
+        }
+        items.sort((a, b) => severityRank(a.severity) - severityRank(b.severity));
+        if (items.length > MAX_SNAPSHOT) items.length = MAX_SNAPSHOT;
+        return { name: 'css', items };
+    }
+
     #enable() {
         if (this.#active || typeof document === 'undefined' || typeof window === 'undefined') return;
         this.#active = true;
@@ -293,6 +392,7 @@ export class CSSAdapter {
         pushInvisible(el, findings);
         pushBlockers(el, findings);
         pushImage(el, findings);
+        pushStacking(el, findings);
         const path = cssPath(el);
         this.core?.sendData('state', { source: this.source, key: 'css.target', value: path });
         this.core?.sendData('state', {
@@ -340,7 +440,7 @@ export class CSSAdapter {
         for (let i = 0; i < findings.length; i++) {
             const hit = findings[i];
             const text = hit.text || hit.kind || '';
-            if (!text || text.startsWith('unreadable sheet:')) continue;
+            if (!text || text.startsWith('unreadable sheet:') || hit.level === 'info') continue;
             if (!rememberIssue(this.#issueLog, `${path}\0${text}`, now, this.issueWindow)) continue;
             const level = hit.level === 'error' ? 'error' : 'warn';
             this.core?.sendData(level, {
@@ -380,20 +480,25 @@ export class CSSAdapter {
     }
 
     #publishIssues() {
-        const bugs = this.#issues.map((entry) => ({
-            level: 'error',
-            key: entry.key,
-            text: formatCause(entry),
-            targets: entry.targets.map((target) => ({
-                text: target.text,
-                onSelect: () => this.#pin(target.el)
-            }))
-        }));
+        const bugs = [];
         const notes = this.#notes.map((note) => ({
             level: 'info',
             key: note.text,
             text: note.text
         }));
+        for (let i = 0; i < this.#issues.length; i++) {
+            const entry = this.#issues[i];
+            const item = {
+                key: entry.key,
+                text: formatCause(entry),
+                targets: entry.targets.map((target) => ({
+                    text: target.text,
+                    onSelect: () => this.#pin(target.el)
+                }))
+            };
+            if (entry.level === 'info') notes.push({ ...item, level: 'info' });
+            else bugs.push({ ...item, level: 'error' });
+        }
         this.core?.publishIssues(bugs.concat(notes));
     }
 
@@ -598,9 +703,11 @@ function pushNegativeMargins(el, findings) {
 const ISSUE_RANK = Object.freeze({
     overflow: 0,
     blocker: 1,
+    stack: 1,
     invisible: 2,
     image: 3,
-    important: 4
+    important: 4,
+    hint: 6
 });
 
 /**
@@ -729,12 +836,32 @@ export function pushStickyIssue(list, entry, max = 10) {
 
 export function describeCause(kind, path) {
     if (kind === 'overflows viewport') {
-        return { key: `overflow\0${path}`, type: 'overflow', cause: path };
+        return { key: `overflow\0${path}`, type: 'overflow', cause: path, reason: '', level: 'error' };
     }
     const prefix = 'click blocked by ';
     if (typeof kind === 'string' && kind.startsWith(prefix)) {
         const cause = kind.slice(prefix.length);
-        return { key: `block\0${cause}`, type: 'block', cause };
+        return { key: `block\0${cause}`, type: 'block', cause, reason: '', level: 'error' };
+    }
+    const stack = typeof kind === 'string' ? kind.match(/^stacking context \(([^)]+)\) by (.+)$/) : null;
+    if (stack) {
+        return {
+            key: `stack\0${stack[2]}\0${stack[1]}`,
+            type: 'stack',
+            cause: stack[2],
+            reason: stack[1],
+            level: 'error'
+        };
+    }
+    const hint = typeof kind === 'string' ? kind.match(/^will-change (.+?) by (.+)$/) : null;
+    if (hint) {
+        return {
+            key: `will\0${hint[2]}\0${hint[1]}`,
+            type: 'stack-hint',
+            cause: hint[2],
+            reason: hint[1],
+            level: 'info'
+        };
     }
     return null;
 }
@@ -760,6 +887,8 @@ export function addCause(list, entry, max = 10) {
         key: described.key,
         type: described.type,
         cause: described.cause,
+        reason: described.reason || '',
+        level: described.level || 'error',
         targets
     });
     return rest.slice(0, max);
@@ -771,10 +900,96 @@ export function formatCause(entry) {
         const noun = count === 1 ? 'element' : 'elements';
         return `${entry.cause} blocks clicks on ${count} ${noun}`;
     }
+    if (entry.type === 'stack') {
+        const noun = count === 1 ? 'child' : 'children';
+        return `${entry.cause} creates stacking context (${entry.reason}) - z-index of ${count} ${noun} is trapped`;
+    }
+    if (entry.type === 'stack-hint') {
+        const noun = count === 1 ? 'child' : 'children';
+        return `${entry.cause} will-change: ${entry.reason} — z-index of ${count} ${noun} stays in this layer`;
+    }
     if (count <= 1) return `${entry.cause} overflows viewport`;
     return `${entry.cause} overflows viewport · ${count} elements`;
 }
 
+/**
+ * Properties that create a stacking context. `will-change` for transform or
+ * opacity is only a hint: it may promote a layer, it is not reported as a bug.
+ * @param {{ transform?: string, opacity?: string, filter?: string, position?: string, zIndex?: string, willChange?: string, getPropertyValue?: (name: string) => string }} style
+ */
+export function stackingReasons(style) {
+    const read = (prop, camel) => {
+        if (style && typeof style.getPropertyValue === 'function') {
+            const raw = style.getPropertyValue(prop);
+            if (raw) return String(raw).trim();
+        }
+        if (style && style[camel] != null && style[camel] !== '') return String(style[camel]).trim();
+        return '';
+    };
+    const bugs = [];
+    const transform = read('transform', 'transform');
+    if (transform && transform !== 'none') bugs.push('transform');
+    const opacity = parseFloat(read('opacity', 'opacity'));
+    if (Number.isFinite(opacity) && opacity < 1) bugs.push('opacity');
+    const filter = read('filter', 'filter');
+    if (filter && filter !== 'none') bugs.push('filter');
+    const position = read('position', 'position') || 'static';
+    const zIndex = read('z-index', 'zIndex') || 'auto';
+    if (position !== 'static' && zIndex !== 'auto') bugs.push('z-index');
+    const hint = willChangeHint(read('will-change', 'willChange'));
+    return { bugs, hint };
+}
+
+function willChangeHint(value) {
+    if (!value || value === 'auto') return '';
+    const parts = value.split(',').map((part) => part.trim().toLowerCase());
+    const hit = [];
+    for (let i = 0; i < parts.length; i++) {
+        if ((parts[i] === 'transform' || parts[i] === 'opacity') && !hit.includes(parts[i])) hit.push(parts[i]);
+    }
+    return hit.join(', ');
+}
+
+function pushStacking(el, findings) {
+    if (!el || typeof getComputedStyle !== 'function' || !el.parentElement) return;
+    const own = getComputedStyle(el);
+    const ownZ = own.zIndex || own.getPropertyValue?.('z-index') || 'auto';
+    if (!ownZ || ownZ === 'auto') return;
+    let node = el.parentElement;
+    while (node && node.nodeType === 1) {
+        if (isBeeChrome(node)) return;
+        const found = stackingReasons(getComputedStyle(node));
+        const ancestor = cssPath(node);
+        if (found.bugs.length) {
+            const reason = found.bugs[0];
+            findings.push({
+                level: 'error',
+                rank: ISSUE_RANK.stack,
+                score: 35,
+                kind: `stacking context (${reason}) by ${ancestor}`,
+                text: `z-index trapped by ${ancestor} (${reason})`
+            });
+            if (found.hint) findings.push(stackHint(ancestor, found.hint));
+            return;
+        }
+        if (found.hint) {
+            findings.push(stackHint(ancestor, found.hint));
+            return;
+        }
+        node = node.parentElement;
+    }
+}
+
+function stackHint(ancestor, hint) {
+    return {
+        level: 'info',
+        rank: ISSUE_RANK.hint,
+        score: 1,
+        kind: `will-change ${hint} by ${ancestor}`,
+        text: `will-change: ${hint} on ${ancestor}`
+    };
+}
+
 function sameTarget(a, b) {
     if (a.el && b.el) return a.el === b.el;
     return a.text === b.text;
@@ -802,6 +1017,34 @@ function nowMs() {
     return typeof performance !== 'undefined' ? performance.now() : Date.now();
 }
 
+function reportSeverity(level) {
+    if (level === 'error') return 'error';
+    if (level === 'warn' || level === 'warning') return 'warn';
+    return 'ok';
+}
+
+function severityRank(level) {
+    if (level === 'error') return 0;
+    if (level === 'warn') return 1;
+    return 2;
+}
+
+function causeRule(type) {
+    if (type === 'block') return 'click blocked';
+    if (type === 'stack') return 'stacking context';
+    if (type === 'stack-hint') return 'will-change';
+    return 'overflow';
+}
+
+function plainRule(kind) {
+    const text = String(kind || '');
+    if (text.startsWith('!important')) return '!important';
+    if (text.startsWith('invisible text')) return 'invisible text';
+    if (text.startsWith('negative margin')) return 'negative margin';
+    if (text === 'distorted image') return 'distorted image';
+    return text;
+}
+
 function issue(kind, rank, score) {
     return { level: 'error', rank, score, kind, text: kind };
 }