bee-ladybug 0.2.0 → 0.3.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
@@ -113,6 +116,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 |
@@ -197,6 +202,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 +223,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.3.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 +252,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 +290,16 @@ 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.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, PythonBridge, tipi, ESLint, gancio AI multi-provider. Fatto.
+2. **npm 0.3.0** — `npm publish`.
 
 ## Come contribuire
 

package/package.json

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

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.2.0';
+export const BEE_LADYBUG_VERSION = '0.3.0';
 
 export const CORE_DEFAULTS = Object.freeze({
     toggleKey: 'F2',
@@ -93,7 +93,8 @@ export class BeeLadybugCore {
         this.#onKeyDown = (event) => this.#handleKey(event);
         this.#onTick = (now) => this.#tick(now);
         this.#started = false;
-        this.#assistant = null;
+        this.#assistants = new Map();
+        this.#activeAssistant = null;
         this.#askBusy = false;
 
         this.ui = null;
@@ -124,7 +125,10 @@ export class BeeLadybugCore {
     #onKeyDown;
     #onTick;
     #started;
-    #assistant;
+    /** @type {Map<string, { name: string, complete: Function }>} */
+    #assistants;
+    /** @type {string | null} */
+    #activeAssistant;
     #askBusy;
 
     /**
@@ -159,51 +163,86 @@ export class BeeLadybugCore {
     }
 
     get hasAssistant() {
-        return Boolean(this.#assistant);
+        return Boolean(this.#activeProvider());
     }
 
     get assistantBusy() {
         return this.#askBusy;
     }
 
+    /** Registered provider names, insertion order. */
+    getAssistants() {
+        return [...this.#assistants.keys()];
+    }
+
     /**
-     * Plug in any model. BeeLadybug does not call OpenAI/Ollama itself.
+     * Add a model without dropping the others. Same `name` updates that slot.
+     * The first registration becomes active; later ones do not steal focus.
      * @param {{ name?: string, complete: (input: { question: string, snapshot: object }) => unknown }} provider
      */
-    setAssistant(provider) {
-        const next = normalizeAssistant(provider);
-        if (!next) {
+    registerAssistant(provider) {
+        return this.#putAssistant(provider, { activate: !this.#activeAssistant, via: 'registerAssistant' });
+    }
+
+    /**
+     * @param {string} name
+     */
+    setActiveAssistant(name) {
+        const key = String(name || '');
+        if (!this.#assistants.has(key)) {
             this.sendData('warn', {
                 source: 'ai',
-                message: 'setAssistant() needs { complete(ctx) }. No vendor is bundled.'
+                message: `No assistant named "${key}". bee.registerAssistant({ name, complete }) first.`
             });
             return this;
         }
-        this.#assistant = next;
-        this.sendData('state', { source: 'ai', key: 'ai.assist', value: next.name });
-        this.sendData('log', {
-            source: 'ai',
-            message: `assistant ready (${next.name})`
-        });
+        this.#activeAssistant = key;
+        this.sendData('state', { source: 'ai', key: 'ai.assist', value: key });
+        this.sendData('log', { source: 'ai', message: `assistant active (${key})` });
         return this;
     }
 
-    clearAssistant() {
-        this.#assistant = null;
-        this.sendData('state', { source: 'ai', key: 'ai.assist', value: 'off' });
+    /**
+     * Register and activate one provider. Does not remove the others.
+     * @param {{ name?: string, complete: (input: { question: string, snapshot: object }) => unknown }} provider
+     */
+    setAssistant(provider) {
+        return this.#putAssistant(provider, { activate: true, via: 'setAssistant' });
+    }
+
+    /**
+     * @param {string} [name] omit to drop every provider
+     */
+    clearAssistant(name) {
+        if (name == null || name === '') {
+            this.#assistants.clear();
+            this.#activeAssistant = null;
+        } else {
+            const key = String(name);
+            this.#assistants.delete(key);
+            if (this.#activeAssistant === key) {
+                this.#activeAssistant = this.#assistants.keys().next().value ?? null;
+            }
+        }
+        this.sendData('state', {
+            source: 'ai',
+            key: 'ai.assist',
+            value: this.#activeAssistant ?? 'off'
+        });
         return this;
     }
 
     /**
-     * Send recent telemetry to the registered assistant and print the answer.
+     * Send recent telemetry to the active assistant and print the answer.
      * @param {string} [question]
      * @returns {Promise<string|null>}
      */
     async ask(question = 'Diagnose the current telemetry.') {
-        if (!this.#assistant) {
+        const assistant = this.#activeProvider();
+        if (!assistant) {
             this.sendData('warn', {
                 source: 'ai',
-                message: 'No assistant. bee.setAssistant({ name, complete }) then ASK AI.'
+                message: 'No assistant. bee.registerAssistant({ name, complete }) then ASK AI.'
             });
             return null;
         }
@@ -217,10 +256,10 @@ export class BeeLadybugCore {
         this.sendData('log', { source: 'ai', message: `ask: ${q}` });
         try {
             const snapshot = buildAssistantSnapshot(this, q);
-            const raw = await this.#assistant.complete({ question: q, snapshot });
+            const raw = await assistant.complete({ question: q, snapshot });
             const text = String(raw ?? '').trim() || '(empty answer)';
             this.sendData('log', { source: 'ai', message: text });
-            this.sendData('state', { source: 'ai', key: 'ai.assist', value: this.#assistant.name });
+            this.sendData('state', { source: 'ai', key: 'ai.assist', value: assistant.name });
             return text;
         } catch (err) {
             this.sendData('error', {
@@ -230,7 +269,7 @@ export class BeeLadybugCore {
             this.sendData('state', {
                 source: 'ai',
                 key: 'ai.assist',
-                value: this.#assistant?.name ?? 'error'
+                value: assistant?.name ?? 'error'
             });
             return null;
         } finally {
@@ -238,6 +277,37 @@ export class BeeLadybugCore {
         }
     }
 
+    #activeProvider() {
+        return this.#activeAssistant ? this.#assistants.get(this.#activeAssistant) ?? null : null;
+    }
+
+    /**
+     * @param {{ name?: string, complete: Function }} provider
+     * @param {{ activate: boolean, via: string }} opts
+     */
+    #putAssistant(provider, opts) {
+        const next = normalizeAssistant(provider);
+        if (!next) {
+            this.sendData('warn', {
+                source: 'ai',
+                message: `${opts.via}() needs { complete(ctx) }. No vendor is bundled.`
+            });
+            return this;
+        }
+        this.#assistants.set(next.name, next);
+        if (opts.activate) this.#activeAssistant = next.name;
+        this.sendData('state', {
+            source: 'ai',
+            key: 'ai.assist',
+            value: this.#activeAssistant ?? next.name
+        });
+        this.sendData('log', {
+            source: 'ai',
+            message: `assistant ready (${next.name})`
+        });
+        return this;
+    }
+
 
     start() {
         if (this.#started) return this;
@@ -280,7 +350,8 @@ export class BeeLadybugCore {
         this.#history.clear();
         this.#hud.clear();
         this.#latest.clear();
-        this.#assistant = null;
+        this.#assistants.clear();
+        this.#activeAssistant = null;
         this.#askBusy = false;
         this.ui?.destroy();
         this.ui = null;
@@ -307,6 +378,10 @@ export class BeeLadybugCore {
         return this.visible ? this.hide() : this.show();
     }
 
+    /**
+     * Stops the simulated clock only. Overlay RAF keeps running.
+     * Adapters must listen for `sys` packets with `op: 'freeze'`.
+     */
     freeze() {
         if (this.frozen) return this;
         this.frozen = true;
@@ -365,7 +440,8 @@ export class BeeLadybugCore {
             logCount: this.#logs.length,
             hud: this.getHud(),
             mode: this.#modeLabel(),
-            assistant: this.#assistant ? this.#assistant.name : null
+            assistant: this.#activeAssistant,
+            assistants: this.getAssistants()
         };
     }
 

package/src/core/UIOverlay.js

@@ -99,8 +99,14 @@ const STYLES = `
   border: 1px solid rgba(110, 231, 255, 0.35);
   padding: 1px 5px;
 }
-.bl-mode {
+.bl-mode-wrap {
   margin-left: auto;
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+  position: relative;
+}
+.bl-mode {
   font-size: 10px;
   font-weight: 700;
   letter-spacing: 0.08em;
@@ -108,6 +114,50 @@ const STYLES = `
 }
 .bl-mode[data-mode="FREEZE"] { color: #ff3b4e; }
 .bl-mode[data-mode^="SLOW"] { color: #ffd36a; }
+.bl-info {
+  appearance: none;
+  position: relative;
+  flex: 0 0 auto;
+  width: 15px;
+  height: 15px;
+  padding: 0;
+  border: 1px solid rgba(139, 145, 163, 0.7);
+  border-radius: 50%;
+  background: transparent;
+  color: #8b91a3;
+  font: 700 9px ui-monospace, Consolas, monospace;
+  line-height: 1;
+  cursor: help;
+}
+.bl-info:hover,
+.bl-info:focus-visible {
+  color: #ffd36a;
+  border-color: #ffd36a;
+  outline: none;
+}
+.bl-info-tip {
+  display: none;
+  position: absolute;
+  top: calc(100% + 6px);
+  right: 0;
+  width: 228px;
+  padding: 8px 9px;
+  background: #0c0e14;
+  border: 1px solid rgba(255, 211, 106, 0.45);
+  color: #e9edf5;
+  font: 400 10px/1.45 ui-monospace, Consolas, monospace;
+  letter-spacing: 0;
+  text-transform: none;
+  z-index: 3;
+  pointer-events: none;
+  white-space: normal;
+  text-align: left;
+}
+.bl-info:hover .bl-info-tip,
+.bl-info:focus .bl-info-tip,
+.bl-info:focus-visible .bl-info-tip {
+  display: block;
+}
 .bl-stats {
   display: grid;
   grid-template-columns: 1fr 1fr;
@@ -189,6 +239,31 @@ const STYLES = `
   border-color: #ff3b4e;
   color: #fff;
 }
+.bl-providers {
+  display: inline-flex;
+  align-items: center;
+  gap: 3px;
+}
+.bl-providers:empty {
+  display: none;
+}
+.bl-provider {
+  appearance: none;
+  width: 22px;
+  height: 22px;
+  padding: 0;
+  background: #16181f;
+  color: #fff6d8;
+  border: 1px solid rgba(255, 211, 106, 0.45);
+  font: 700 8px ui-monospace, Consolas, monospace;
+  letter-spacing: 0.04em;
+  cursor: pointer;
+}
+.bl-provider[data-hot="true"] {
+  background: #6ee7ff;
+  border-color: #6ee7ff;
+  color: #05060a;
+}
 .bl-hint {
   margin-left: auto;
   font-size: 9px;
@@ -213,6 +288,7 @@ export class UIOverlay {
         this.#stickBottom = true;
         this.#lastLogId = 0;
         this.#mounted = false;
+        this.#providerSig = '';
     }
 
     #host;
@@ -221,6 +297,7 @@ export class UIOverlay {
     #stickBottom;
     #lastLogId;
     #mounted;
+    #providerSig;
 
     /** @param {'auto' | HTMLElement} [target] */
     mount(target = 'auto') {
@@ -247,7 +324,13 @@ export class UIOverlay {
                   <span class="bl-mark" aria-hidden="true"></span>
                   <span class="bl-title">BEE LADYBUG</span>
                   <span class="bl-badge">CORE</span>
-                  <span class="bl-mode" data-el="mode">LIVE</span>
+                  <span class="bl-mode-wrap">
+                    <span class="bl-mode" data-el="mode">LIVE</span>
+                    <button class="bl-info" type="button" aria-describedby="bl-freeze-tip" aria-label="Freeze stops the simulated clock, not this overlay">
+                      <span aria-hidden="true">ⓘ</span>
+                      <span class="bl-info-tip" id="bl-freeze-tip">Freeze does not stop this overlay. It only stops the simulated clock. Adapters must listen for the sys event (op: freeze).</span>
+                    </button>
+                  </span>
                 </div>
                 <div class="bl-stats">
                   <div>HOST <b data-el="hostFps">—</b></div>
@@ -269,6 +352,7 @@ export class UIOverlay {
                   <button class="bl-btn" data-act="freeze" type="button">F4 STOP</button>
                   <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-hint">F2 overlay</span>
                 </div>
               </div>
@@ -286,7 +370,8 @@ export class UIOverlay {
             graphName: this.#root.querySelector('[data-el="graphName"]'),
             graphStats: this.#root.querySelector('[data-el="graphStats"]'),
             hud: this.#root.querySelector('[data-el="hud"]'),
-            console: this.#root.querySelector('[data-el="console"]')
+            console: this.#root.querySelector('[data-el="console"]'),
+            providers: this.#root.querySelector('[data-el="providers"]')
         };
 
         this.#root.querySelector('.bl-foot').addEventListener('click', (event) => {
@@ -297,6 +382,7 @@ export class UIOverlay {
             else if (act === 'freeze') this.core.toggleFreeze();
             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'));
         });
 
         this.#els.console.addEventListener('scroll', () => {
@@ -318,6 +404,7 @@ export class UIOverlay {
         this.#root = null;
         this.#els = null;
         this.#mounted = false;
+        this.#providerSig = '';
         return this;
     }
 
@@ -366,6 +453,7 @@ export class UIOverlay {
         this.#paintGraph(primary);
         this.#renderHud(state.hud);
         this.#syncButtons(state);
+        this.#syncProviders(state);
 
         if (this.#stickBottom) {
             this.#els.console.scrollTop = this.#els.console.scrollHeight;
@@ -424,6 +512,23 @@ export class UIOverlay {
         }
     }
 
+    #syncProviders(state) {
+        const wrap = this.#els.providers;
+        if (!wrap) return;
+        const names = Array.isArray(state.assistants) ? state.assistants : [];
+        const active = state.assistant ?? '';
+        const sig = `${names.join('\0')}\0${active}`;
+        if (sig === this.#providerSig) return;
+        this.#providerSig = sig;
+        let html = '';
+        for (let i = 0; i < names.length; i++) {
+            const name = names[i];
+            const hot = name === active ? 'true' : 'false';
+            html += `<button class="bl-provider" data-act="assist" data-name="${escapeHtml(name)}" data-hot="${hot}" type="button" title="${escapeHtml(name)}">${escapeHtml(abbrevName(name))}</button>`;
+        }
+        wrap.innerHTML = html;
+    }
+
     #paintGraph(series) {
         const canvas = this.#els.graph;
         const ctx = canvas.getContext('2d');
@@ -475,6 +580,11 @@ export class UIOverlay {
     }
 }
 
+function abbrevName(name) {
+    const s = String(name || '?');
+    return s.slice(0, 2).toUpperCase();
+}
+
 function fmtHud(value) {
     if (value == null) return '—';
     if (typeof value === 'number') return Number.isInteger(value) ? String(value) : value.toFixed(2);

package/src/index.d.ts

@@ -58,6 +58,7 @@ export interface CoreState {
     hud: Record<string, HudEntry>;
     mode: string;
     assistant: string | null;
+    assistants: string[];
 }
 
 export interface CoreOptions {
@@ -148,8 +149,11 @@ export class BeeLadybugCore {
     getLatest(type: string): BeePacket | null;
     readonly hasAssistant: boolean;
     readonly assistantBusy: boolean;
+    getAssistants(): string[];
+    registerAssistant(provider: AssistantProvider): this;
+    setActiveAssistant(name: string): this;
     setAssistant(provider: AssistantProvider): this;
-    clearAssistant(): this;
+    clearAssistant(name?: string): this;
     ask(question?: string): Promise<string | null>;
 }