bee-ladybug 0.3.0 → 0.4.1

package/README.MD

@@ -1,7 +1,9 @@
 
 # BeeLadybug
 
-
+<p align="center">
+  <img src="https://raw.githubusercontent.com/antonioprosperi2-svg/BeeLadybug-universal/main/docs/logo.jpg" alt="BeeLadybug" width="720">
+</p>
 
 Universal telemetry and visual inspection overlay.
 
@@ -37,6 +39,8 @@ bee-ladybug/
 │   └── adapters/
 │       ├── CanvasAdapter.js
 │       ├── WebDOMAdapter.js
+│       ├── AntAdapter.js
+│       ├── SpiderAdapter.js
 │       └── python/PythonBridge.js
 ├── examples/
 │   ├── core.html
@@ -96,6 +100,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 |
 
@@ -116,7 +121,7 @@ bee.subscribe((packet) => {
 });
 ```
 
-![Overlay Core: la ⓘ accanto a LIVE spiega che il freeze ferma solo il clock fittizio](docs/overlay-core.jpg)
+![Overlay Core: la ⓘ accanto a LIVE spiega che il freeze ferma solo il clock fittizio](https://raw.githubusercontent.com/antonioprosperi2-svg/BeeLadybug-universal/main/docs/overlay-core.jpg)
 
 ## Tasti
 
@@ -172,6 +177,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()`.
@@ -202,7 +251,7 @@ 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)
+![Overlay PythonBridge: ASK AI e quadratini mock/echo per scegliere il provider](https://raw.githubusercontent.com/antonioprosperi2-svg/BeeLadybug-universal/main/docs/overlay-python.jpg)
 
 ## npm / TypeScript
 
@@ -228,7 +277,7 @@ npm login
 npm publish --access public
 ```
 
-Versione runtime e pacchetto: **0.3.0** (`BEE_LADYBUG_VERSION` e `package.json` devono restare uguali).
+Versione runtime e pacchetto: **0.4.1** (`BEE_LADYBUG_VERSION` e `package.json` devono restare uguali).
 
 ## Assistente AI (gancio, nessun vendor)
 
@@ -293,13 +342,15 @@ bee.applySlowMo(); bee.restoreRealtime();
 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 multi-provider. Fatto.
-2. **npm 0.3.0** — `npm publish`.
+1. **Ora** — Core, adapter, registro toggle overlay, Ant/Spider, PythonBridge, tipi, ESLint, gancio AI multi-provider. Fatto.
+2. **npm 0.4.1** — `npm publish`.
 
 ## Come contribuire
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bee-ladybug",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "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 [];
+    }
+}

package/src/core/BeeLadybugCore.js

@@ -9,7 +9,7 @@
 import { UIOverlay } from './UIOverlay.js';
 import { buildAssistantSnapshot, normalizeAssistant } from './AiAssistant.js';
 
-export const BEE_LADYBUG_VERSION = '0.3.0';
+export const BEE_LADYBUG_VERSION = '0.4.1';
 
 export const CORE_DEFAULTS = Object.freeze({
     toggleKey: 'F2',
@@ -35,7 +35,8 @@ export const WELL_KNOWN_TYPES = Object.freeze([
     'error',
     'state',
     'sys',
-    'clear'
+    'clear',
+    'telemetry'
 ]);
 
 /**
@@ -96,6 +97,7 @@ export class BeeLadybugCore {
         this.#assistants = new Map();
         this.#activeAssistant = null;
         this.#askBusy = false;
+        this.#adapters = new Map();
 
         this.ui = null;
         if (cfg.ui !== false && typeof document !== 'undefined') {
@@ -130,6 +132,8 @@ export class BeeLadybugCore {
     /** @type {string | null} */
     #activeAssistant;
     #askBusy;
+    /** @type {Map<string, { name: string, label: string, enabled: boolean, enable: Function, disable: Function }>} */
+    #adapters;
 
     /**
      * Public adapter contract. `type` is a channel name; `payload` is raw data.
@@ -281,6 +285,86 @@ export class BeeLadybugCore {
         return this.#activeAssistant ? this.#assistants.get(this.#activeAssistant) ?? null : null;
     }
 
+    /**
+     * Register a toggleable diagnostic adapter. The core stores hooks only —
+     * it does not import or special-case adapter modules.
+     * @param {string} name
+     * @param {{ enable: () => void, disable: () => void, label?: string }} hooks
+     */
+    registerAdapter(name, hooks = {}) {
+        const key = String(name || '').trim();
+        if (!key || typeof hooks.enable !== 'function' || typeof hooks.disable !== 'function') {
+            this.sendData('warn', {
+                source: 'core',
+                message: 'registerAdapter() needs a name and { enable, disable }.'
+            });
+            return this;
+        }
+        const label = String(hooks.label || key).trim() || key;
+        this.#adapters.set(key, {
+            name: key,
+            label,
+            enabled: true,
+            enable: hooks.enable,
+            disable: hooks.disable
+        });
+        this.sendData('sys', { op: 'adapter', name: key, registered: true, label, enabled: true });
+        return this;
+    }
+
+    /**
+     * @param {string} name
+     */
+    unregisterAdapter(name) {
+        const key = String(name || '').trim();
+        if (!key || !this.#adapters.has(key)) return this;
+        this.#adapters.delete(key);
+        this.sendData('sys', { op: 'adapter', name: key, registered: false });
+        return this;
+    }
+
+    /** Registered diagnostic adapters, insertion order. */
+    getAdapters() {
+        return [...this.#adapters.values()].map((entry) => ({
+            name: entry.name,
+            label: entry.label,
+            enabled: entry.enabled
+        }));
+    }
+
+    /**
+     * @param {string} name
+     */
+    toggleAdapter(name) {
+        const entry = this.#adapters.get(String(name || '').trim());
+        if (!entry) return this;
+        return this.setAdapterEnabled(entry.name, !entry.enabled);
+    }
+
+    /**
+     * @param {string} name
+     * @param {boolean} enabled
+     */
+    setAdapterEnabled(name, enabled) {
+        const entry = this.#adapters.get(String(name || '').trim());
+        if (!entry) return this;
+        const next = Boolean(enabled);
+        if (entry.enabled === next) return this;
+        try {
+            if (next) entry.enable();
+            else entry.disable();
+            entry.enabled = next;
+        } catch (err) {
+            console.warn('[BeeLadybug] adapter toggle error', err);
+        }
+        this.sendData('sys', {
+            op: 'adapter',
+            name: entry.name,
+            enabled: entry.enabled
+        });
+        return this;
+    }
+
     /**
      * @param {{ name?: string, complete: Function }} provider
      * @param {{ activate: boolean, via: string }} opts
@@ -353,6 +437,7 @@ export class BeeLadybugCore {
         this.#assistants.clear();
         this.#activeAssistant = null;
         this.#askBusy = false;
+        this.#adapters.clear();
         this.ui?.destroy();
         this.ui = null;
         return this;
@@ -441,7 +526,8 @@ export class BeeLadybugCore {
             hud: this.getHud(),
             mode: this.#modeLabel(),
             assistant: this.#activeAssistant,
-            assistants: this.getAssistants()
+            assistants: this.getAssistants(),
+            adapters: this.getAdapters()
         };
     }
 
@@ -553,6 +639,13 @@ export class BeeLadybugCore {
             return;
         }
 
+        if (type === 'telemetry') {
+            const name = String(payload.kind ?? payload.name ?? 'telemetry');
+            const value = numeric(payload.duration ?? payload.value);
+            if (value != null) this.#pushHistory(name, value);
+            return;
+        }
+
         if (isConsoleType(type) || packet.level) {
             this.#pushLog(packet);
         }

package/src/core/UIOverlay.js

@@ -247,6 +247,41 @@ const STYLES = `
 .bl-providers:empty {
   display: none;
 }
+.bl-adapters {
+  display: inline-flex;
+  align-items: center;
+  gap: 3px;
+}
+.bl-adapters:empty {
+  display: none;
+}
+.bl-adapter {
+  appearance: none;
+  background: #16181f;
+  color: #8b91a3;
+  border: 1px solid rgba(139, 145, 163, 0.45);
+  font: 700 9px ui-monospace, Consolas, monospace;
+  letter-spacing: 0.06em;
+  padding: 5px 7px;
+  cursor: pointer;
+}
+.bl-adapter[data-hot="true"] {
+  color: #fff6d8;
+  border-color: #ffd36a;
+}
+.bl-adapter[data-flash="true"] {
+  animation: bl-adapter-flash 0.55s ease;
+}
+@keyframes bl-adapter-flash {
+  0% {
+    background: #ffd36a;
+    color: #05060a;
+    border-color: #ffd36a;
+  }
+  100% {
+    background: #16181f;
+  }
+}
 .bl-provider {
   appearance: none;
   width: 22px;
@@ -271,6 +306,12 @@ const STYLES = `
 }
 @media (prefers-reduced-motion: reduce) {
   .bl-scan { display: none; }
+  .bl-adapter[data-flash="true"] {
+    animation: none;
+    background: #ffd36a;
+    color: #05060a;
+    border-color: #ffd36a;
+  }
 }
 `;
 
@@ -289,6 +330,9 @@ export class UIOverlay {
         this.#lastLogId = 0;
         this.#mounted = false;
         this.#providerSig = '';
+        this.#adapterSig = '';
+        this.#flashAt = new Map();
+        this.#flashTimers = new Map();
     }
 
     #host;
@@ -298,6 +342,9 @@ export class UIOverlay {
     #lastLogId;
     #mounted;
     #providerSig;
+    #adapterSig;
+    #flashAt;
+    #flashTimers;
 
     /** @param {'auto' | HTMLElement} [target] */
     mount(target = 'auto') {
@@ -353,6 +400,7 @@ export class UIOverlay {
                   <button class="bl-btn" data-act="live" type="button">1x LIVE</button>
                   <button class="bl-btn" data-act="ask" type="button">ASK AI</button>
                   <span class="bl-providers" data-el="providers"></span>
+                  <span class="bl-adapters" data-el="adapters"></span>
                   <span class="bl-hint">F2 overlay</span>
                 </div>
               </div>
@@ -371,7 +419,8 @@ export class UIOverlay {
             graphStats: this.#root.querySelector('[data-el="graphStats"]'),
             hud: this.#root.querySelector('[data-el="hud"]'),
             console: this.#root.querySelector('[data-el="console"]'),
-            providers: this.#root.querySelector('[data-el="providers"]')
+            providers: this.#root.querySelector('[data-el="providers"]'),
+            adapters: this.#root.querySelector('[data-el="adapters"]')
         };
 
         this.#root.querySelector('.bl-foot').addEventListener('click', (event) => {
@@ -383,6 +432,7 @@ export class UIOverlay {
             else if (act === 'live') this.core.restoreRealtime();
             else if (act === 'ask') this.core.ask();
             else if (act === 'assist') this.core.setActiveAssistant(btn.getAttribute('data-name'));
+            else if (act === 'adapter') this.core.toggleAdapter(btn.getAttribute('data-name'));
         });
 
         this.#els.console.addEventListener('scroll', () => {
@@ -405,6 +455,9 @@ export class UIOverlay {
         this.#els = null;
         this.#mounted = false;
         this.#providerSig = '';
+        this.#adapterSig = '';
+        this.#clearFlashTimers();
+        this.#flashAt.clear();
         return this;
     }
 
@@ -423,6 +476,7 @@ export class UIOverlay {
     onPacket(packet) {
         if (!this.#els || !packet) return;
         if (packet.type === 'sys') return;
+        this.#flashAdapterButton(packet);
         if (packet.level || packet.type === 'log' || packet.type === 'warn' || packet.type === 'error') {
             this.#appendLine(packet);
         }
@@ -454,6 +508,7 @@ export class UIOverlay {
         this.#renderHud(state.hud);
         this.#syncButtons(state);
         this.#syncProviders(state);
+        this.#syncAdapters(state);
 
         if (this.#stickBottom) {
             this.#els.console.scrollTop = this.#els.console.scrollHeight;
@@ -529,6 +584,63 @@ export class UIOverlay {
         wrap.innerHTML = html;
     }
 
+    #syncAdapters(state) {
+        const wrap = this.#els.adapters;
+        if (!wrap) return;
+        const list = Array.isArray(state.adapters) ? state.adapters : [];
+        const sig = list.map((entry) => `${entry.name}\0${entry.label}\0${entry.enabled ? 1 : 0}`).join('\n');
+        if (sig === this.#adapterSig) return;
+        this.#adapterSig = sig;
+        let html = '';
+        for (let i = 0; i < list.length; i++) {
+            const entry = list[i];
+            const hot = entry.enabled ? 'true' : 'false';
+            html += `<button class="bl-adapter" data-act="adapter" data-name="${escapeHtml(entry.name)}" data-hot="${hot}" type="button" title="${escapeHtml(entry.label)}">${escapeHtml(entry.label)}</button>`;
+        }
+        wrap.innerHTML = html;
+    }
+
+    #flashAdapterButton(packet) {
+        if (packet.type !== 'warn' && packet.type !== 'telemetry') return;
+        const wrap = this.#els.adapters;
+        if (!wrap || !this.core || typeof this.core.getAdapters !== 'function') return;
+        const name = packet.source;
+        if (!this.core.getAdapters().some((entry) => entry.name === name)) return;
+
+        const escaped = typeof CSS !== 'undefined' && typeof CSS.escape === 'function'
+            ? CSS.escape(name)
+            : name.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+        const btn = wrap.querySelector(`[data-name="${escaped}"]`);
+        if (!btn) return;
+
+        const now = typeof performance !== 'undefined' ? performance.now() : Date.now();
+        const last = this.#flashAt.get(name) ?? 0;
+        if (now - last < 1500) return;
+        this.#flashAt.set(name, now);
+
+        btn.dataset.flash = 'false';
+        void btn.offsetWidth;
+        btn.dataset.flash = 'true';
+
+        const prev = this.#flashTimers.get(name);
+        if (prev && typeof clearTimeout === 'function') clearTimeout(prev);
+        if (typeof setTimeout !== 'function') return;
+        const timer = setTimeout(() => {
+            this.#flashTimers.delete(name);
+            if (btn.dataset.flash === 'true') btn.dataset.flash = 'false';
+        }, 560);
+        this.#flashTimers.set(name, timer);
+    }
+
+    #clearFlashTimers() {
+        if (typeof clearTimeout !== 'function') {
+            this.#flashTimers.clear();
+            return;
+        }
+        for (const timer of this.#flashTimers.values()) clearTimeout(timer);
+        this.#flashTimers.clear();
+    }
+
     #paintGraph(series) {
         const canvas = this.#els.graph;
         const ctx = canvas.getContext('2d');

package/src/index.d.ts

@@ -14,7 +14,8 @@ export const WELL_KNOWN_TYPES: readonly [
     'error',
     'state',
     'sys',
-    'clear'
+    'clear',
+    'telemetry'
 ];
 
 export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
@@ -59,6 +60,7 @@ export interface CoreState {
     mode: string;
     assistant: string | null;
     assistants: string[];
+    adapters: AdapterInfo[];
 }
 
 export interface CoreOptions {
@@ -106,6 +108,18 @@ export interface AssistantProvider {
     complete(input: { question: string; snapshot: AssistantSnapshot }): unknown;
 }
 
+export interface AdapterHooks {
+    enable(): void;
+    disable(): void;
+    label?: string;
+}
+
+export interface AdapterInfo {
+    name: string;
+    label: string;
+    enabled: boolean;
+}
+
 export function formatSimTime(ms: number): string;
 
 export class BeeLadybugCore {
@@ -155,6 +169,11 @@ export class BeeLadybugCore {
     setAssistant(provider: AssistantProvider): this;
     clearAssistant(name?: string): this;
     ask(question?: string): Promise<string | null>;
+    registerAdapter(name: string, hooks: AdapterHooks): this;
+    unregisterAdapter(name: string): this;
+    getAdapters(): AdapterInfo[];
+    toggleAdapter(name: string): this;
+    setAdapterEnabled(name: string, enabled: boolean): this;
 }
 
 export class UIOverlay {
@@ -193,6 +212,7 @@ export interface CanvasAdapterOptions {
     entities?: CanvasEntity[];
     overlay?: boolean;
     computeCollisions?: boolean;
+    autoPump?: boolean;
     colorActive?: string;
     colorColliding?: string;
     colorInactive?: string;
@@ -209,11 +229,13 @@ export class CanvasAdapter {
     entities: CanvasEntity[];
     overlayEnabled: boolean;
     computeCollisions: boolean;
+    autoPump: boolean;
     frozen: boolean;
     timeScale: number;
     constructor(core: BeeLadybugCore, options?: CanvasAdapterOptions);
     attach(): this;
     detach(): this;
+    startAutoPump(): this;
     setCanvas(canvas: HTMLCanvasElement | null): this;
     setEntities(entities: CanvasEntity[]): this;
     pump(ctx?: CanvasRenderingContext2D): this;
@@ -250,6 +272,44 @@ export class WebDOMAdapter {
     pump(): this;
 }
 
+export interface AntAdapterOptions {
+    root?: ParentNode | null;
+    threshold?: number;
+    windowMs?: number;
+    source?: string;
+}
+
+export const ANT_ADAPTER_DEFAULTS: Required<Omit<AntAdapterOptions, 'root'>>;
+
+export class AntAdapter {
+    core: BeeLadybugCore | null;
+    root: ParentNode | null;
+    threshold: number;
+    windowMs: number;
+    source: string;
+    constructor(core: BeeLadybugCore, options?: AntAdapterOptions);
+    attach(): this;
+    detach(): this;
+}
+
+export interface SpiderAdapterOptions {
+    longTaskThreshold?: number;
+    resourceThreshold?: number;
+    source?: string;
+}
+
+export const SPIDER_ADAPTER_DEFAULTS: Required<SpiderAdapterOptions>;
+
+export class SpiderAdapter {
+    core: BeeLadybugCore | null;
+    longTaskThreshold: number;
+    resourceThreshold: number;
+    source: string;
+    constructor(core: BeeLadybugCore, options?: SpiderAdapterOptions);
+    attach(): this;
+    detach(): this;
+}
+
 export type PythonBridgeStatus = 'idle' | 'connecting' | 'open' | 'closed';
 
 export interface PythonBridgeOptions {

package/src/index.js

@@ -2,4 +2,6 @@ export { BeeLadybugCore, BEE_LADYBUG_VERSION, CORE_DEFAULTS, WELL_KNOWN_TYPES, f
 export { UIOverlay } from './core/UIOverlay.js';
 export { CanvasAdapter, CANVAS_ADAPTER_DEFAULTS } from './adapters/CanvasAdapter.js';
 export { WebDOMAdapter, WEB_DOM_ADAPTER_DEFAULTS } from './adapters/WebDOMAdapter.js';
+export { AntAdapter, ANT_ADAPTER_DEFAULTS } from './adapters/AntAdapter.js';
+export { SpiderAdapter, SPIDER_ADAPTER_DEFAULTS } from './adapters/SpiderAdapter.js';
 export { PythonBridge, PYTHON_BRIDGE_DEFAULTS } from './adapters/python/PythonBridge.js';