bee-ladybug 0.2.0 → 0.4.0

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.4.0';
 
 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'
 ]);
 
 /**
@@ -93,8 +94,10 @@ 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.#adapters = new Map();
 
         this.ui = null;
         if (cfg.ui !== false && typeof document !== 'undefined') {
@@ -124,8 +127,13 @@ export class BeeLadybugCore {
     #onKeyDown;
     #onTick;
     #started;
-    #assistant;
+    /** @type {Map<string, { name: string, complete: Function }>} */
+    #assistants;
+    /** @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.
@@ -159,51 +167,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 +260,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 +273,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 +281,117 @@ export class BeeLadybugCore {
         }
     }
 
+    #activeProvider() {
+        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
+     */
+    #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,8 +434,10 @@ 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.#adapters.clear();
         this.ui?.destroy();
         this.ui = null;
         return this;
@@ -307,6 +463,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 +525,9 @@ 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(),
+            adapters: this.getAdapters()
         };
     }
 
@@ -477,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

@@ -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,66 @@ const STYLES = `
   border-color: #ff3b4e;
   color: #fff;
 }
+.bl-providers {
+  display: inline-flex;
+  align-items: center;
+  gap: 3px;
+}
+.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;
+  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;
@@ -196,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;
+  }
 }
 `;
 
@@ -213,6 +329,10 @@ export class UIOverlay {
         this.#stickBottom = true;
         this.#lastLogId = 0;
         this.#mounted = false;
+        this.#providerSig = '';
+        this.#adapterSig = '';
+        this.#flashAt = new Map();
+        this.#flashTimers = new Map();
     }
 
     #host;
@@ -221,6 +341,10 @@ export class UIOverlay {
     #stickBottom;
     #lastLogId;
     #mounted;
+    #providerSig;
+    #adapterSig;
+    #flashAt;
+    #flashTimers;
 
     /** @param {'auto' | HTMLElement} [target] */
     mount(target = 'auto') {
@@ -247,7 +371,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 +399,8 @@ 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-adapters" data-el="adapters"></span>
                   <span class="bl-hint">F2 overlay</span>
                 </div>
               </div>
@@ -286,7 +418,9 @@ 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"]'),
+            adapters: this.#root.querySelector('[data-el="adapters"]')
         };
 
         this.#root.querySelector('.bl-foot').addEventListener('click', (event) => {
@@ -297,6 +431,8 @@ 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'));
+            else if (act === 'adapter') this.core.toggleAdapter(btn.getAttribute('data-name'));
         });
 
         this.#els.console.addEventListener('scroll', () => {
@@ -318,6 +454,10 @@ export class UIOverlay {
         this.#root = null;
         this.#els = null;
         this.#mounted = false;
+        this.#providerSig = '';
+        this.#adapterSig = '';
+        this.#clearFlashTimers();
+        this.#flashAt.clear();
         return this;
     }
 
@@ -336,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);
         }
@@ -366,6 +507,8 @@ export class UIOverlay {
         this.#paintGraph(primary);
         this.#renderHud(state.hud);
         this.#syncButtons(state);
+        this.#syncProviders(state);
+        this.#syncAdapters(state);
 
         if (this.#stickBottom) {
             this.#els.console.scrollTop = this.#els.console.scrollHeight;
@@ -424,6 +567,80 @@ 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;
+    }
+
+    #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');
@@ -475,6 +692,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);