bee-ladybug 0.2.0 → 0.4.0

package/{README.md → README.MD}

@@ -1,5 +1,8 @@
+
 # BeeLadybug
 
+
+
 Universal telemetry and visual inspection overlay.
 
 BeeLadybug is **not** a Canvas widget. It is a small open-source debugger
@@ -34,6 +37,8 @@ bee-ladybug/
 │   └── adapters/
 │       ├── CanvasAdapter.js
 │       ├── WebDOMAdapter.js
+│       ├── AntAdapter.js
+│       ├── SpiderAdapter.js
 │       └── python/PythonBridge.js
 ├── examples/
 │   ├── core.html
@@ -93,6 +98,7 @@ Gli adapter parlano **solo** così. Uno scalare viene avvolto in `{ value }`.
 | `log` | `{ message, level?, source? }` | console |
 | `warn` | `{ message, source? }` | console ambra |
 | `error` | `{ message, source? }` | console rossa |
+| `telemetry` | `{ kind?, duration?, source? }` | history + lampeggio pulsante adapter |
 | `clear` | `{ channel?: 'logs'\|'history'\|'hud' }` | reset buffer |
 | `sys` | emesso dal Core | freeze / visibilità / scala |
 
@@ -113,6 +119,8 @@ bee.subscribe((packet) => {
 });
 ```
 
+![Overlay Core: la ⓘ accanto a LIVE spiega che il freeze ferma solo il clock fittizio](docs/overlay-core.jpg)
+
 ## Tasti
 
 | Tasto | Azione |
@@ -167,6 +175,50 @@ adapter.attach();
 
 Traduce il DOM in pacchetti: nodo sotto il puntatore, box model (margin / padding / content), conteggio nodi, mutazioni (`+n -n attr`). `F4` congela l'hover. `F2` nasconde overlay e highlight. Il Core non sa che esiste HTML.
 
+## Registro adapter (overlay)
+
+Il Core non conosce ANT/SPIDER. Gli adapter si iscrivono con hook propri; l'overlay disegna un toggle per ciascuno.
+
+```js
+bee.registerAdapter('probe', {
+  label: 'PROBE',
+  enable: () => observer.observe(root, opts),
+  disable: () => observer.disconnect()
+});
+adapter.detach(); // chiama bee.unregisterAdapter('probe')
+```
+
+Click sul pulsante → `enable()` / `disable()`. Un pacchetto `warn` o `telemetry` con `source` uguale al nome registrato fa lampeggiare quel pulsante, al massimo una volta ogni 1.5s.
+
+## AntAdapter
+
+```js
+import { BeeLadybugCore, AntAdapter } from './src/index.js';
+
+const bee = new BeeLadybugCore();
+const ant = new AntAdapter(bee, {
+  root: document.body,
+  threshold: 30          // mutazioni / secondo per nodo
+});
+ant.attach();
+```
+
+`MutationObserver` indipendente da `WebDOMAdapter` (possono condividere lo stesso `root`). Se un nodo supera la soglia, arriva un `warn` `source: 'ant'`.
+
+## SpiderAdapter
+
+```js
+import { BeeLadybugCore, SpiderAdapter } from './src/index.js';
+
+const bee = new BeeLadybugCore();
+const spider = new SpiderAdapter(bee, {
+  resourceThreshold: 500 // ms
+});
+spider.attach();
+```
+
+`PerformanceObserver`: `longtask` > 50ms → `telemetry`; risorse > soglia → `warn`. Se il browser non espone `longtask` (Firefox/Safari), un log una tantum e quella parte si spegne senza errori.
+
 ## PythonBridge
 
 Python non vede l'overlay. Manda JSON. Il browser lo srotola in `sendData()`.
@@ -197,6 +249,8 @@ python examples/python/sender.py
 
 Poi aprire `http://localhost:8080/examples/python.html` e Connect. I pulsanti mock funzionano anche a processo spento.
 
+![Overlay PythonBridge: ASK AI e quadratini mock/echo per scegliere il provider](docs/overlay-python.jpg)
+
 ## npm / TypeScript
 
 ```bash
@@ -216,14 +270,19 @@ npm run typecheck
 npm run lint
 ```
 
-Versione runtime e pacchetto: **0.2.0** (`BEE_LADYBUG_VERSION` e `package.json` devono restare uguali). Su npm ora risulta `0.1.0`: il prossimo `npm publish` sarà `0.2.0`.
+```bash
+npm login
+npm publish --access public
+```
+
+Versione runtime e pacchetto: **0.4.0** (`BEE_LADYBUG_VERSION` e `package.json` devono restare uguali).
 
 ## Assistente AI (gancio, nessun vendor)
 
-BeeLadybug **non** chiama OpenAI, Claude o Ollama. Lo sviluppatore innesta il proprio modello:
+BeeLadybug **non** chiama OpenAI, Claude o Ollama. Lo sviluppatore innesta i propri modelli. `registerAssistant` **aggiunge** (non sostituisce gli altri). `setActiveAssistant(name)` sceglie chi risponde a **ASK AI**.
 
 ```js
-bee.setAssistant({
+bee.registerAssistant({
   name: 'ollama',
   async complete({ question, snapshot }) {
     const res = await fetch('http://127.0.0.1:11434/api/generate', {
@@ -240,17 +299,18 @@ bee.setAssistant({
   }
 });
 
+bee.registerAssistant({
+  name: 'mock',
+  complete({ snapshot }) {
+    return `logs=${snapshot.logs.length}`;
+  }
+});
+
+bee.setActiveAssistant('ollama');
 await bee.ask('perché il loss sale?');
 ```
 
-Il Core manda un **snapshot** (log recenti, HUD, metriche) a `complete()`. Chiavi tipo `token`/`password` vengono redacted. In overlay: pulsante **ASK AI**. Senza `setAssistant`, il bottone spiega come collegarlo.
-
-## API Core
-
-```bash
-npm login
-npm publish --access public
-```
+Il Core manda un **snapshot** (log recenti, HUD, metriche) a `complete()`. Chiavi tipo `token`/`password` vengono redacted. In overlay: pulsante **ASK AI** e un quadratino per ogni provider; quello attivo è evidenziato. Senza provider, il bottone spiega come collegarlo. `setAssistant` resta come scorciatoia: registra e attiva, senza cancellare gli altri.
 
 ## API Core
 
@@ -277,15 +337,18 @@ bee.getHud();
 bee.show(); bee.hide(); bee.toggle();
 bee.freeze(); bee.unfreeze(); bee.toggleFreeze();
 bee.applySlowMo(); bee.restoreRealtime();
-bee.setAssistant({ name: 'mock', complete: async ({ snapshot }) => 'ok' });
+bee.registerAssistant({ name: 'mock', complete: async ({ snapshot }) => 'ok' });
+bee.setActiveAssistant('mock');
 await bee.ask('why fps drop?');
+bee.registerAdapter('probe', { label: 'PROBE', enable() {}, disable() {} });
+bee.toggleAdapter('probe');
 bee.destroy();
 ```
 
 ## Roadmap
 
-1. **Ora** — Core, adapter, PythonBridge, tipi, ESLint, gancio AI. Fatto.
-2. **npm 0.2.0** — `npm publish` (registry è ancora 0.1.0).
+1. **Ora** — Core, adapter, registro toggle overlay, Ant/Spider, PythonBridge, tipi, ESLint, gancio AI multi-provider. Fatto.
+2. **npm 0.4.0** — `npm publish`.
 
 ## Come contribuire
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bee-ladybug",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Universal telemetry and visual inspection overlay for Canvas, DOM, Python and AI flows.",
   "type": "module",
   "main": "src/index.js",
@@ -19,7 +19,7 @@
     "scripts": {
         "typecheck": "tsc --noEmit",
         "lint": "eslint src examples",
-        "test": "node --test tests/**/*.test.js"
+        "test": "node --test tests/*.test.js"
     },
   "keywords": [
     "debug",
@@ -45,7 +45,7 @@
   },
   "homepage": "https://github.com/antonioprosperi2-svg/BeeLadybug-universal#readme",
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
     "devDependencies": {
         "@eslint/js": "^9.36.0",

package/src/adapters/AntAdapter.js

@@ -0,0 +1,144 @@
+/**
+ * AntAdapter — DOM mutation rate tracker.
+ *
+ * Independent MutationObserver. Can sit on the same root as WebDOMAdapter.
+ * The core must never import this file.
+ *
+ * @example
+ * const ant = new AntAdapter(core, { root: document.body, threshold: 30 });
+ * ant.attach();
+ */
+
+export const ANT_ADAPTER_DEFAULTS = Object.freeze({
+    threshold: 30,
+    windowMs: 1000,
+    source: 'ant'
+});
+
+export class AntAdapter {
+    /**
+     * @param {import('../core/BeeLadybugCore.js').BeeLadybugCore} core
+     * @param {Partial<typeof ANT_ADAPTER_DEFAULTS> & {
+     *   root?: ParentNode | null
+     * }} [options]
+     */
+    constructor(core, options = {}) {
+        const cfg = { ...ANT_ADAPTER_DEFAULTS, ...options };
+        this.core = core;
+        this.root = options.root !== undefined
+            ? options.root
+            : (typeof document !== 'undefined' ? document.body : null);
+        this.threshold = positive(cfg.threshold, ANT_ADAPTER_DEFAULTS.threshold);
+        this.windowMs = positive(cfg.windowMs, ANT_ADAPTER_DEFAULTS.windowMs);
+        this.source = cfg.source;
+
+        this.#attached = false;
+        this.#observer = null;
+        this.#counts = new WeakMap();
+        this.#onMutate = (records) => this.#ingest(records);
+    }
+
+    #attached;
+    #observer;
+    #counts;
+    #onMutate;
+
+    attach() {
+        if (this.#attached) return this;
+        this.#attached = true;
+        this.#enable();
+        this.core?.registerAdapter('ant', {
+            enable: () => this.#enable(),
+            disable: () => this.#disable(),
+            label: 'ANT'
+        });
+        this.core?.sendData('log', {
+            source: this.source,
+            message: 'AntAdapter attached. Watching DOM mutation rate.'
+        });
+        return this;
+    }
+
+    detach() {
+        if (!this.#attached) return this;
+        this.#attached = false;
+        this.#disable();
+        this.core?.unregisterAdapter('ant');
+        return this;
+    }
+
+    #enable() {
+        if (!this.#attached || this.#observer) return;
+        if (typeof MutationObserver === 'undefined' || !this.root) return;
+        this.#counts = new WeakMap();
+        this.#observer = new MutationObserver(this.#onMutate);
+        try {
+            this.#observer.observe(this.root, {
+                childList: true,
+                subtree: true,
+                attributes: true,
+                characterData: true
+            });
+        } catch {
+            this.#observer.disconnect();
+            this.#observer = null;
+        }
+    }
+
+    #disable() {
+        if (this.#observer) this.#observer.disconnect();
+        this.#observer = null;
+        this.#counts = new WeakMap();
+    }
+
+    #ingest(records) {
+        if (!this.#attached || !this.core || !records?.length) return;
+        const now = typeof performance !== 'undefined' ? performance.now() : Date.now();
+        for (let i = 0; i < records.length; i++) {
+            const node = records[i]?.target;
+            if (!node || isBeeChrome(node)) continue;
+
+            let slot = this.#counts.get(node);
+            if (!slot || now - slot.windowStart >= this.windowMs) {
+                slot = { count: 0, windowStart: now, warned: false };
+                this.#counts.set(node, slot);
+            }
+            slot.count += 1;
+            if (slot.count < this.threshold || slot.warned) continue;
+
+            slot.warned = true;
+            const selector = nodeSelector(node);
+            this.core.sendData('warn', {
+                source: this.source,
+                message: `High Mutation Rate on ${selector}`,
+                node: selector
+            });
+        }
+    }
+}
+
+function positive(value, fallback) {
+    const n = Number(value);
+    return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+
+function nodeSelector(node) {
+    const el = node && node.nodeType === 1 ? node : node?.parentElement;
+    if (!el || !el.tagName) return 'node';
+    if (el.id) return `#${el.id}`;
+    const cls = el.classList && el.classList[0];
+    if (cls) return `.${cls}`;
+    return el.tagName.toLowerCase();
+}
+
+function isBeeChrome(node) {
+    let el = node && node.nodeType === 1 ? node : node?.parentElement;
+    while (el) {
+        const tag = el.tagName;
+        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;
+        el = el.parentElement;
+    }
+    return false;
+}

package/src/adapters/CanvasAdapter.js

@@ -15,11 +15,17 @@
  * adapter.attach();
  * // after updating entity positions each host frame:
  * adapter.pump();
+ *
+ * @example
+ * // third-party / bookmarklet: no access to the host loop
+ * const remote = new CanvasAdapter(core, { canvas, entities, autoPump: true });
+ * remote.attach();
  */
 
 export const CANVAS_ADAPTER_DEFAULTS = Object.freeze({
     overlay: true,
     computeCollisions: true,
+    autoPump: false,
     colorActive: '#3dff6a',
     colorColliding: '#ff3b3b',
     colorInactive: '#8a8a8a',
@@ -41,6 +47,7 @@ export class CanvasAdapter {
         this.entities = options.entities ?? [];
         this.overlayEnabled = cfg.overlay;
         this.computeCollisions = cfg.computeCollisions;
+        this.autoPump = Boolean(cfg.autoPump);
         this.colorActive = cfg.colorActive;
         this.colorColliding = cfg.colorColliding;
         this.colorInactive = cfg.colorInactive;
@@ -54,19 +61,35 @@ export class CanvasAdapter {
         this.#attached = false;
         this.#overlay = null;
         this.#unsubscribe = null;
+        this.#rafId = 0;
+        this.#pumpFromAuto = false;
+        this.#manualPumpWarned = false;
         this.#lastPump = 0;
         this.#fps = 0;
         this.#wasColliding = new Set();
         this.#onResize = () => this.#syncOverlay();
+        this.#onTick = () => {
+            this.#rafId = requestAnimationFrame(this.#onTick);
+            this.#pumpFromAuto = true;
+            try {
+                this.pump();
+            } finally {
+                this.#pumpFromAuto = false;
+            }
+        };
     }
 
     #attached;
     #overlay;
     #unsubscribe;
+    #rafId;
+    #pumpFromAuto;
+    #manualPumpWarned;
     #lastPump;
     #fps;
     #wasColliding;
     #onResize;
+    #onTick;
 
     attach() {
         if (this.#attached) return this;
@@ -83,6 +106,7 @@ export class CanvasAdapter {
             window.addEventListener('resize', this.#onResize);
             window.addEventListener('scroll', this.#onResize, true);
         }
+        if (this.autoPump) this.startAutoPump();
 
         this.core?.sendData('log', {
             source: this.source,
@@ -99,6 +123,7 @@ export class CanvasAdapter {
     detach() {
         if (!this.#attached) return this;
         this.#attached = false;
+        this.#stopAutoPumpLoop();
         if (this.#unsubscribe) this.#unsubscribe();
         this.#unsubscribe = null;
         this.#unmountOverlay();
@@ -109,6 +134,20 @@ export class CanvasAdapter {
         return this;
     }
 
+    /**
+     * Drive `pump()` from an internal `requestAnimationFrame` loop.
+     * Use this when the host game loop cannot call `pump()` (bookmarklet / console).
+     */
+    startAutoPump() {
+        this.autoPump = true;
+        if (!this.#attached) return this;
+        if (this.#rafId) return this;
+        if (typeof requestAnimationFrame !== 'function') return this;
+        this.#manualPumpWarned = false;
+        this.#rafId = requestAnimationFrame(this.#onTick);
+        return this;
+    }
+
     /** @param {HTMLCanvasElement | null} canvas */
     setCanvas(canvas) {
         this.canvas = canvas;
@@ -126,10 +165,15 @@ export class CanvasAdapter {
      * Call once per host frame, after entity positions are updated.
      * Pass a 2D context only if overlay is disabled and you want hitboxes
      * drawn onto the game canvas itself.
+     * Ignored (with a warning) while `autoPump` owns the frame loop.
      * @param {CanvasRenderingContext2D} [ctx]
      */
     pump(ctx) {
         if (!this.#attached || !this.core) return this;
+        if (this.#rafId && !this.#pumpFromAuto) {
+            this.#warnManualPump();
+            return this;
+        }
 
         const now = typeof performance !== 'undefined' ? performance.now() : Date.now();
         if (this.#lastPump) {
@@ -147,6 +191,25 @@ export class CanvasAdapter {
         return this;
     }
 
+    #stopAutoPumpLoop() {
+        if (this.#rafId && typeof cancelAnimationFrame === 'function') {
+            cancelAnimationFrame(this.#rafId);
+        }
+        this.#rafId = 0;
+        this.#pumpFromAuto = false;
+        this.#manualPumpWarned = false;
+    }
+
+    #warnManualPump() {
+        if (this.#manualPumpWarned) return;
+        this.#manualPumpWarned = true;
+        const message = 'pump() skipped: autoPump already drives the frame loop.';
+        if (typeof console !== 'undefined' && typeof console.warn === 'function') {
+            console.warn(`[BeeLadybug] CanvasAdapter ${message}`);
+        }
+        this.core.sendData('warn', { source: this.source, message });
+    }
+
     #onCore(packet) {
         if (packet.type !== 'sys') return;
         const op = packet.payload.op;

package/src/adapters/SpiderAdapter.js

@@ -0,0 +1,160 @@
+/**
+ * SpiderAdapter — long-task and slow-resource tracker.
+ *
+ * Native PerformanceObserver only. The core must never import this file.
+ *
+ * @example
+ * const spider = new SpiderAdapter(core, { resourceThreshold: 500 });
+ * spider.attach();
+ */
+
+export const SPIDER_ADAPTER_DEFAULTS = Object.freeze({
+    longTaskThreshold: 50,
+    resourceThreshold: 500,
+    source: 'spider'
+});
+
+export class SpiderAdapter {
+    /**
+     * @param {import('../core/BeeLadybugCore.js').BeeLadybugCore} core
+     * @param {Partial<typeof SPIDER_ADAPTER_DEFAULTS>} [options]
+     */
+    constructor(core, options = {}) {
+        const cfg = { ...SPIDER_ADAPTER_DEFAULTS, ...options };
+        this.core = core;
+        this.longTaskThreshold = positive(cfg.longTaskThreshold, SPIDER_ADAPTER_DEFAULTS.longTaskThreshold);
+        this.resourceThreshold = positive(cfg.resourceThreshold, SPIDER_ADAPTER_DEFAULTS.resourceThreshold);
+        this.source = cfg.source;
+
+        this.#attached = false;
+        this.#longObserver = null;
+        this.#resourceObserver = null;
+        this.#longTaskMissingLogged = false;
+        this.#onLongTask = (list) => this.#ingestLongTasks(list);
+        this.#onResource = (list) => this.#ingestResources(list);
+    }
+
+    #attached;
+    #longObserver;
+    #resourceObserver;
+    #longTaskMissingLogged;
+    #onLongTask;
+    #onResource;
+
+    attach() {
+        if (this.#attached) return this;
+        this.#attached = true;
+        this.#enable();
+        this.core?.registerAdapter('spider', {
+            enable: () => this.#enable(),
+            disable: () => this.#disable(),
+            label: 'SPIDER'
+        });
+        this.core?.sendData('log', {
+            source: this.source,
+            message: 'SpiderAdapter attached. Watching long tasks and slow resources.'
+        });
+        return this;
+    }
+
+    detach() {
+        if (!this.#attached) return this;
+        this.#attached = false;
+        this.#disable();
+        this.core?.unregisterAdapter('spider');
+        return this;
+    }
+
+    #enable() {
+        if (!this.#attached) return;
+        if (typeof PerformanceObserver !== 'function') {
+            this.#logLongTaskUnavailable();
+            return;
+        }
+        const types = supportedEntryTypes();
+        if (types.includes('longtask')) this.#watchLongTasks();
+        else this.#logLongTaskUnavailable();
+        if (types.includes('resource')) this.#watchResources();
+    }
+
+    #disable() {
+        if (this.#longObserver) this.#longObserver.disconnect();
+        if (this.#resourceObserver) this.#resourceObserver.disconnect();
+        this.#longObserver = null;
+        this.#resourceObserver = null;
+    }
+
+    #watchLongTasks() {
+        if (this.#longObserver) return;
+        try {
+            this.#longObserver = new PerformanceObserver(this.#onLongTask);
+            this.#longObserver.observe({ entryTypes: ['longtask'] });
+        } catch {
+            this.#longObserver = null;
+            this.#logLongTaskUnavailable();
+        }
+    }
+
+    #watchResources() {
+        if (this.#resourceObserver) return;
+        try {
+            this.#resourceObserver = new PerformanceObserver(this.#onResource);
+            this.#resourceObserver.observe({ entryTypes: ['resource'] });
+        } catch {
+            this.#resourceObserver = null;
+        }
+    }
+
+    #ingestLongTasks(list) {
+        if (!this.#attached || !this.core) return;
+        const entries = list?.getEntries?.() ?? [];
+        for (let i = 0; i < entries.length; i++) {
+            const entry = entries[i];
+            if (!entry || entry.duration <= this.longTaskThreshold) continue;
+            this.core.sendData('telemetry', {
+                source: this.source,
+                kind: 'longtask',
+                duration: entry.duration,
+                attribution: entry.attribution?.[0]?.containerType ?? 'unknown'
+            });
+        }
+    }
+
+    #ingestResources(list) {
+        if (!this.#attached || !this.core) return;
+        const entries = list?.getEntries?.() ?? [];
+        for (let i = 0; i < entries.length; i++) {
+            const entry = entries[i];
+            if (!entry || entry.duration <= this.resourceThreshold) continue;
+            this.core.sendData('warn', {
+                source: this.source,
+                message: `Risorsa lenta: ${entry.name} (${Math.round(entry.duration)}ms)`
+            });
+        }
+    }
+
+    #logLongTaskUnavailable() {
+        if (this.#longTaskMissingLogged) return;
+        this.#longTaskMissingLogged = true;
+        this.core?.sendData('log', {
+            source: this.source,
+            message: 'Long task detection non disponibile in questo browser'
+        });
+    }
+}
+
+function positive(value, fallback) {
+    const n = Number(value);
+    return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+
+function supportedEntryTypes() {
+    if (typeof PerformanceObserver !== 'function') return [];
+    const list = PerformanceObserver.supportedEntryTypes;
+    if (!list) return [];
+    try {
+        return Array.from(list);
+    } catch {
+        return [];
+    }
+}