bee-ladybug 0.5.4 → 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
@@ -350,6 +364,7 @@ const bee = new BeeLadybugCore({
   toggleKey: 'F2',
   slowKey: 'F3',
   freezeKey: 'F4',
+  exportKey: 'F8',
   slowScale: 0.25,
   maxLogs: 250,
   historySize: 120,
@@ -368,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.4",
+  "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,
@@ -191,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;
@@ -919,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 };
 }

package/src/adapters/CanvasAdapter.js

@@ -4,6 +4,7 @@
  * Reads generic AABB entities, measures host FPS, computes collisions,
  * and pushes packets into the core. Hitboxes are drawn on a stacked
  * overlay canvas so the game pixels stay untouched.
+ * `snapshot()` hands the report hitboxes, collisions, and FPS min/avg/max.
  *
  * The core must never import this file.
  *
@@ -59,6 +60,7 @@ export class CanvasAdapter {
         this.timeScale = 1;
 
         this.#attached = false;
+        this.#reporting = true;
         this.#overlay = null;
         this.#unsubscribe = null;
         this.#rafId = 0;
@@ -66,6 +68,7 @@ export class CanvasAdapter {
         this.#manualPumpWarned = false;
         this.#lastPump = 0;
         this.#fps = 0;
+        this.#fpsSamples = [];
         this.#wasColliding = new Set();
         this.#onResize = () => this.#syncOverlay();
         this.#onTick = () => {
@@ -80,6 +83,7 @@ export class CanvasAdapter {
     }
 
     #attached;
+    #reporting;
     #overlay;
     #unsubscribe;
     #rafId;
@@ -87,6 +91,7 @@ export class CanvasAdapter {
     #manualPumpWarned;
     #lastPump;
     #fps;
+    #fpsSamples;
     #wasColliding;
     #onResize;
     #onTick;
@@ -108,6 +113,15 @@ export class CanvasAdapter {
         }
         if (this.autoPump) this.startAutoPump();
 
+        this.#reporting = true;
+        this.core?.registerAdapter('canvas', {
+            label: 'CANVAS',
+            enabled: true,
+            enable: () => this.#enable(),
+            disable: () => this.#disable(),
+            snapshot: () => this.snapshot()
+        });
+
         this.core?.sendData('log', {
             source: this.source,
             message: `CanvasAdapter attached (${this.entities.length} entities).`
@@ -126,6 +140,7 @@ export class CanvasAdapter {
         this.#stopAutoPumpLoop();
         if (this.#unsubscribe) this.#unsubscribe();
         this.#unsubscribe = null;
+        this.core?.unregisterAdapter('canvas');
         this.#unmountOverlay();
         if (typeof window !== 'undefined') {
             window.removeEventListener('resize', this.#onResize);
@@ -161,6 +176,28 @@ export class CanvasAdapter {
         return this;
     }
 
+    /**
+     * Hitboxes currently on the entity list, plus FPS min/avg/max.
+     * Returns null when the adapter is not attached. The core stores this
+     * function and does not read the rows.
+     * @returns {{ name: string, items: Array<{ severity: string, selector: string, rule: string, value: string, source: string }> } | null}
+     */
+    snapshot() {
+        if (!this.#attached) return null;
+        const boxes = this.#collectBoxes();
+        this.#markCollisions(boxes);
+        const items = boxes.map((box) => ({
+            severity: box.hit ? 'warn' : 'ok',
+            selector: box.name,
+            rule: 'hitbox',
+            value: `${box.x},${box.y} ${box.w}x${box.h}${box.hit ? ' colliding' : ''}`,
+            source: this.source
+        }));
+        const fps = this.#fpsItem();
+        if (fps) items.push(fps);
+        return { name: 'canvas', items };
+    }
+
     /**
      * Call once per host frame, after entity positions are updated.
      * Pass a 2D context only if overlay is disabled and you want hitboxes
@@ -174,6 +211,7 @@ export class CanvasAdapter {
             this.#warnManualPump();
             return this;
         }
+        if (!this.#reporting) return this;
 
         const now = typeof performance !== 'undefined' ? performance.now() : Date.now();
         if (this.#lastPump) {
@@ -257,6 +295,8 @@ export class CanvasAdapter {
         if (!tracked && boxes[0]) tracked = boxes[0];
 
         if (this.#fps > 0) {
+            this.#fpsSamples.push(this.#fps);
+            if (this.#fpsSamples.length > 120) this.#fpsSamples.shift();
             this.core.sendData('fps', { value: this.#fps, source: this.source });
         }
         this.core.sendData('metric', {
@@ -374,7 +414,49 @@ export class CanvasAdapter {
         overlay.style.top = `${rect.top}px`;
         overlay.style.width = `${rect.width}px`;
         overlay.style.height = `${rect.height}px`;
-        overlay.style.display = this.core && this.core.visible === false ? 'none' : 'block';
+        const hidden = !this.#reporting || (this.core && this.core.visible === false);
+        overlay.style.display = hidden ? 'none' : 'block';
+    }
+
+    #enable() {
+        this.#reporting = true;
+        this.#syncOverlay();
+    }
+
+    #disable() {
+        this.#reporting = false;
+        this.#syncOverlay();
+    }
+
+    #fpsItem() {
+        const stats = this.#fpsStats();
+        if (!stats) return null;
+        return {
+            severity: 'ok',
+            selector: 'host',
+            rule: 'fps',
+            value: `min ${round1(stats.min)} avg ${round1(stats.avg)} max ${round1(stats.max)}`,
+            source: this.source
+        };
+    }
+
+    #fpsStats() {
+        const history = typeof this.core?.getHistory === 'function' ? this.core.getHistory('fps') : null;
+        if (history && Array.isArray(history.values) && history.values.length) {
+            return { min: history.min, avg: history.avg, max: history.max };
+        }
+        const samples = this.#fpsSamples;
+        if (!samples.length) return null;
+        let min = samples[0];
+        let max = samples[0];
+        let sum = 0;
+        for (let i = 0; i < samples.length; i++) {
+            const value = samples[i];
+            if (value < min) min = value;
+            if (value > max) max = value;
+            sum += value;
+        }
+        return { min, avg: sum / samples.length, max };
     }
 }
 
@@ -409,3 +491,7 @@ function idFromKey(id) {
     const parts = String(id).split(':');
     return parts[parts.length - 1] || id;
 }
+
+function round1(value) {
+    return Math.round(Number(value) * 10) / 10;
+}

package/src/adapters/SpiderAdapter.js

@@ -1,13 +1,16 @@
 /**
  * SpiderAdapter — long-task and slow-resource tracker.
  *
- * Native PerformanceObserver only. The core must never import this file.
+ * Native PerformanceObserver only. `snapshot()` keeps the long tasks and
+ * slow resources already seen. The core must never import this file.
  *
  * @example
  * const spider = new SpiderAdapter(core, { resourceThreshold: 500 });
  * spider.attach();
  */
 
+const MAX_SPIDER = 40;
+
 export const SPIDER_ADAPTER_DEFAULTS = Object.freeze({
     longTaskThreshold: 50,
     resourceThreshold: 500,
@@ -30,6 +33,8 @@ export class SpiderAdapter {
         this.#longObserver = null;
         this.#resourceObserver = null;
         this.#longTaskMissingLogged = false;
+        this.#longTasks = [];
+        this.#resources = [];
         this.#onLongTask = (list) => this.#ingestLongTasks(list);
         this.#onResource = (list) => this.#ingestResources(list);
     }
@@ -38,6 +43,8 @@ export class SpiderAdapter {
     #longObserver;
     #resourceObserver;
     #longTaskMissingLogged;
+    #longTasks;
+    #resources;
     #onLongTask;
     #onResource;
 
@@ -48,7 +55,8 @@ export class SpiderAdapter {
         this.core?.registerAdapter('spider', {
             enable: () => this.#enable(),
             disable: () => this.#disable(),
-            label: 'SPIDER'
+            label: 'SPIDER',
+            snapshot: () => this.snapshot()
         });
         this.core?.sendData('log', {
             source: this.source,
@@ -65,6 +73,36 @@ export class SpiderAdapter {
         return this;
     }
 
+    /**
+     * Long tasks and slow resources kept since attach. Returns null when detached.
+     * @returns {{ name: string, items: Array<{ severity: string, selector: string, rule: string, value: string, source: string }> } | null}
+     */
+    snapshot() {
+        if (!this.#attached) return null;
+        const items = [];
+        for (let i = 0; i < this.#longTasks.length; i++) {
+            const entry = this.#longTasks[i];
+            items.push({
+                severity: 'warn',
+                selector: entry.attribution,
+                rule: 'longtask',
+                value: `${entry.duration}ms`,
+                source: this.source
+            });
+        }
+        for (let i = 0; i < this.#resources.length; i++) {
+            const entry = this.#resources[i];
+            items.push({
+                severity: 'warn',
+                selector: entry.name,
+                rule: 'resource',
+                value: `${entry.duration}ms`,
+                source: this.source
+            });
+        }
+        return { name: 'spider', items };
+    }
+
     #enable() {
         if (!this.#attached) return;
         if (typeof PerformanceObserver !== 'function') {
@@ -111,6 +149,10 @@ export class SpiderAdapter {
         for (let i = 0; i < entries.length; i++) {
             const entry = entries[i];
             if (!entry || entry.duration <= this.longTaskThreshold) continue;
+            remember(this.#longTasks, {
+                attribution: entry.attribution?.[0]?.containerType ?? 'unknown',
+                duration: Math.round(entry.duration)
+            });
             this.core.sendData('telemetry', {
                 source: this.source,
                 kind: 'longtask',
@@ -126,6 +168,10 @@ export class SpiderAdapter {
         for (let i = 0; i < entries.length; i++) {
             const entry = entries[i];
             if (!entry || entry.duration <= this.resourceThreshold) continue;
+            remember(this.#resources, {
+                name: String(entry.name || 'resource'),
+                duration: Math.round(entry.duration)
+            });
             this.core.sendData('warn', {
                 source: this.source,
                 message: `Risorsa lenta: ${entry.name} (${Math.round(entry.duration)}ms)`
@@ -143,6 +189,11 @@ export class SpiderAdapter {
     }
 }
 
+function remember(list, entry) {
+    list.unshift(entry);
+    if (list.length > MAX_SPIDER) list.pop();
+}
+
 function positive(value, fallback) {
     const n = Number(value);
     return Number.isFinite(n) && n > 0 ? n : fallback;