bee-ladybug 0.1.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Antonio Prosperi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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
@@ -27,22 +30,24 @@ funziona sopra un gioco, sopra una pagina, o da solo in una sandbox.
 bee-ladybug/
 ├── src/
 │   ├── index.js                 # API pubblica
+│   ├── index.d.ts               # tipi npm / tsc
 │   ├── core/
-│   │   ├── BeeLadybugCore.js    # stato, clock, sendData
-│   │   └── UIOverlay.js         # console scura + sparkline
+│   │   ├── BeeLadybugCore.js
+│   │   └── UIOverlay.js
 │   └── adapters/
-│       ├── CanvasAdapter.js     # hitbox / FPS / collisioni Canvas 2D
-│       ├── WebDOMAdapter.js     # box model / hover / mutazioni HTML
-│       └── python/
-│           └── PythonBridge.js  # futuro: WebSocket → sendData
+│       ├── CanvasAdapter.js
+│       ├── WebDOMAdapter.js
+│       └── python/PythonBridge.js
 ├── examples/
-│   ├── core-sandbox.js          # demo senza adapter
 │   ├── core.html
-│   ├── canvas-sandbox.js        # demo CanvasAdapter
-│   ├── dom-sandbox.js
-│   └── dom.html
-├── index.html
+│   ├── canvas-sandbox.js
+│   ├── dom.html
+│   ├── python.html
+│   └── python/sender.py
+├── tsconfig.json
 ├── package.json
+├── LICENSE
+├── index.html
 └── README.md
 ```
 
@@ -111,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 |
@@ -165,6 +172,99 @@ 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.
 
+## PythonBridge
+
+Python non vede l'overlay. Manda JSON. Il browser lo srotola in `sendData()`.
+
+```js
+import { BeeLadybugCore, PythonBridge } from './src/index.js';
+
+const bee = new BeeLadybugCore();
+const bridge = new PythonBridge(bee, { url: 'ws://127.0.0.1:8765' });
+bridge.connect();
+
+// stesso parser, senza socket:
+bridge.ingest({ type: 'metric', payload: { name: 'loss', value: 0.12 } });
+```
+
+Forma del filo:
+
+```json
+{ "type": "log", "payload": { "message": "epoch 3" } }
+{ "type": "error", "message": "CUDA OOM" }
+```
+
+Sender di esempio (solo stdlib, nessun pip):
+
+```bash
+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
+npm install
+npm run typecheck
+```
+
+```js
+import { BeeLadybugCore } from 'bee-ladybug';
+```
+
+Il runtime resta JavaScript ESM. I tipi stanno in `src/index.d.ts` (`package.json` → `"types"`).
+Keyword e repository puntano a **BeeLadybug-universal**, non a BeeEngine.
+
+```bash
+npm run typecheck
+npm run lint
+```
+
+```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 i propri modelli. `registerAssistant` **aggiunge** (non sostituisce gli altri). `setActiveAssistant(name)` sceglie chi risponde a **ASK AI**.
+
+```js
+bee.registerAssistant({
+  name: 'ollama',
+  async complete({ question, snapshot }) {
+    const res = await fetch('http://127.0.0.1:11434/api/generate', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        model: 'llama3',
+        prompt: `${question}\n${JSON.stringify(snapshot)}`,
+        stream: false
+      })
+    });
+    const data = await res.json();
+    return data.response;
+  }
+});
+
+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** 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
 
 ```js
@@ -190,14 +290,16 @@ bee.getHud();
 bee.show(); bee.hide(); bee.toggle();
 bee.freeze(); bee.unfreeze(); bee.toggleFreeze();
 bee.applySlowMo(); bee.restoreRealtime();
+bee.registerAssistant({ name: 'mock', complete: async ({ snapshot }) => 'ok' });
+bee.setActiveAssistant('mock');
+await bee.ask('why fps drop?');
 bee.destroy();
 ```
 
 ## Roadmap
 
-1. **Ora** — Core + overlay + CanvasAdapter + WebDOMAdapter. Fatto.
-2. **PythonBridge** — WebSocket JSON `{ type, payload }` verso `sendData`.
-3. **Pacchetto npm** — `import { BeeLadybugCore } from 'bee-ladybug'`.
+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,23 +1,56 @@
 {
   "name": "bee-ladybug",
-  "version": "0.1.0",
-  "description": "Universal telemetry and visual inspection overlay for Canvas, DOM, bots, Python and AI flows.",
+  "version": "0.3.0",
+  "description": "Universal telemetry and visual inspection overlay for Canvas, DOM, Python and AI flows.",
   "type": "module",
   "main": "src/index.js",
   "module": "src/index.js",
+  "types": "src/index.d.ts",
   "exports": {
-    ".": "./src/index.js"
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    }
   },
   "files": [
     "src"
   ],
-  "license": "MIT",
+    "scripts": {
+        "typecheck": "tsc --noEmit",
+        "lint": "eslint src examples",
+        "test": "node --test tests/**/*.test.js"
+    },
   "keywords": [
     "debug",
     "telemetry",
     "overlay",
     "observability",
+    "devtools",
     "canvas",
-    "devtools"
-  ]
-}
+    "dom",
+    "python",
+    "websocket",
+    "ai",
+    "esm"
+  ],
+  "author": "Antonio Prosperi",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/antonioprosperi2-svg/BeeLadybug-universal.git"
+  },
+  "bugs": {
+    "url": "https://github.com/antonioprosperi2-svg/BeeLadybug-universal/issues"
+  },
+  "homepage": "https://github.com/antonioprosperi2-svg/BeeLadybug-universal#readme",
+  "engines": {
+    "node": ">=18"
+  },
+    "devDependencies": {
+        "@eslint/js": "^9.36.0",
+        "eslint": "^10.8.1",
+        "globals": "^16.0.0",
+        "typescript": "^5.7.0"
+    }
+}

package/src/adapters/python/PythonBridge.js

@@ -1,40 +1,242 @@
 /**
- * PythonBridge — future inbound channel for Python / AI processes.
+ * PythonBridge — inbound channel for Python / AI / headless processes.
  *
- * Planned transport: WebSocket (or HTTP ingest) that unpacks JSON packets
- * and calls core.sendData(type, payload). The core stays browser-side;
- * Python never talks to the overlay directly.
+ * Speaks WebSocket JSON and calls core.sendData(type, payload).
+ * The core stays browser-side; Python never talks to the overlay.
  *
- * Expected wire shape:
- *   { "type": "log"|"error"|"metric"|"fps"|"state", "payload": { ... } }
+ * Wire shape (either form):
+ *   { "type": "metric", "payload": { "name": "loss", "value": 0.12 } }
+ *   { "type": "log", "message": "epoch 3" }
+ *
+ * ingest() is the same parser used by the socket, so tests and the mock
+ * demo do not need a live Python process.
  */
+
+export const PYTHON_BRIDGE_DEFAULTS = Object.freeze({
+    url: 'ws://127.0.0.1:8765',
+    autoReconnect: true,
+    reconnectMs: 1500,
+    source: 'python'
+});
+
 export class PythonBridge {
     /**
      * @param {import('../../core/BeeLadybugCore.js').BeeLadybugCore} core
-     * @param {{ url?: string }} [options]
+     * @param {Partial<typeof PYTHON_BRIDGE_DEFAULTS>} [options]
      */
     constructor(core, options = {}) {
+        const cfg = { ...PYTHON_BRIDGE_DEFAULTS, ...options };
         this.core = core;
-        this.url = options.url ?? 'ws://127.0.0.1:8765';
+        this.url = cfg.url;
+        this.autoReconnect = cfg.autoReconnect;
+        this.reconnectMs = cfg.reconnectMs;
+        this.source = cfg.source;
+        this.status = 'idle';
+
         this.#socket = null;
+        this.#wanted = false;
+        this.#timer = 0;
+        this.#packets = 0;
+        this.#retries = 0;
     }
 
     #socket;
+    #wanted;
+    #timer;
+    #packets;
+    #retries;
 
-    connect() {
-        this.core?.sendData('log', {
-            source: 'python',
-            level: 'warn',
-            message: `PythonBridge reserved (${this.url}). WebSocket ingest comes after adapters.`
-        });
+    get connected() {
+        return this.status === 'open';
+    }
+
+    connect(url) {
+        if (url) this.url = url;
+        this.#wanted = true;
+        this.#retries = 0;
+        this.#open();
         return this;
     }
 
     disconnect() {
+        this.#wanted = false;
+        this.#clearTimer();
         if (this.#socket) {
-            this.#socket.close();
+            try {
+                this.#socket.close();
+            } catch {
+                /* already closing */
+            }
             this.#socket = null;
         }
+        this.#setStatus('idle');
+        this.core?.sendData('log', {
+            source: this.source,
+            message: 'PythonBridge disconnected.'
+        });
+        return this;
+    }
+
+    /**
+     * Parse one wire message (object, JSON string, or array) into sendData().
+     * @param {unknown} raw
+     */
+    ingest(raw) {
+        if (!this.core) return this;
+        if (raw == null) return this;
+
+        let data = raw;
+        if (typeof raw === 'string') {
+            const text = raw.trim();
+            if (!text) return this;
+            try {
+                data = JSON.parse(text);
+            } catch {
+                this.core.sendData('error', {
+                    source: this.source,
+                    message: `bad JSON: ${text.slice(0, 96)}`
+                });
+                return this;
+            }
+        }
+
+        if (Array.isArray(data)) {
+            for (let i = 0; i < data.length; i++) this.ingest(data[i]);
+            return this;
+        }
+
+        if (typeof data !== 'object') return this;
+
+        const type = data.type || data.channel;
+        if (typeof type !== 'string' || !type) {
+            this.core.sendData('warn', {
+                source: this.source,
+                message: 'packet missing type'
+            });
+            return this;
+        }
+
+        const payload = unpackPayload(data, this.source);
+        this.#packets += 1;
+        this.core.sendData(type, payload);
+        this.core.sendData('state', {
+            source: this.source,
+            key: 'py.packets',
+            value: this.#packets
+        });
         return this;
     }
+
+    #open() {
+        if (!this.#wanted) return;
+        if (typeof WebSocket === 'undefined') {
+            this.core?.sendData('error', {
+                source: this.source,
+                message: 'WebSocket API missing in this runtime.'
+            });
+            this.#setStatus('closed');
+            return;
+        }
+
+        this.#clearTimer();
+        if (this.#socket) {
+            try {
+                this.#socket.close();
+            } catch {
+                /* ignore */
+            }
+        }
+
+        this.#setStatus('connecting');
+        if (this.#retries === 0) {
+            this.core?.sendData('log', {
+                source: this.source,
+                message: `PythonBridge connecting ${this.url}`
+            });
+        }
+
+        let socket;
+        try {
+            socket = new WebSocket(this.url);
+        } catch (err) {
+            this.core?.sendData('error', {
+                source: this.source,
+                message: `connect failed: ${err instanceof Error ? err.message : String(err)}`
+            });
+            this.#setStatus('closed');
+            this.#scheduleReconnect();
+            return;
+        }
+
+        this.#socket = socket;
+        socket.addEventListener('open', () => {
+            if (socket !== this.#socket) return;
+            this.#setStatus('open');
+            this.#retries = 0;
+            this.core?.sendData('log', {
+                source: this.source,
+                message: `PythonBridge open (${this.url})`
+            });
+        });
+        socket.addEventListener('message', (event) => {
+            if (socket !== this.#socket) return;
+            this.ingest(event.data);
+        });
+        socket.addEventListener('close', () => {
+            if (socket !== this.#socket) return;
+            this.#socket = null;
+            this.#setStatus('closed');
+            if (this.#retries === 0) {
+                this.core?.sendData('warn', {
+                    source: this.source,
+                    message: 'PythonBridge socket closed.'
+                });
+            }
+            this.#retries += 1;
+            this.#scheduleReconnect();
+        });
+        socket.addEventListener('error', () => {
+            if (this.#retries > 0) return;
+            this.core?.sendData('error', {
+                source: this.source,
+                message: `PythonBridge socket error (${this.url})`
+            });
+        });
+    }
+
+    #scheduleReconnect() {
+        if (!this.#wanted || !this.autoReconnect) return;
+        this.#clearTimer();
+        this.#timer = setTimeout(() => this.#open(), this.reconnectMs);
+    }
+
+    #clearTimer() {
+        if (this.#timer && typeof clearTimeout === 'function') clearTimeout(this.#timer);
+        this.#timer = 0;
+    }
+
+    #setStatus(status) {
+        this.status = status;
+        this.core?.sendData('state', {
+            source: this.source,
+            key: 'py.status',
+            value: status
+        });
+    }
+}
+
+function unpackPayload(data, source) {
+    const body = data.payload != null && typeof data.payload === 'object' && !Array.isArray(data.payload)
+        ? { ...data.payload }
+        : omitType(data);
+    if (!body.source) body.source = source;
+    return body;
+}
+
+function omitType(data) {
+    const out = { ...data };
+    delete out.type;
+    delete out.channel;
+    delete out.payload;
+    return out;
 }

package/src/core/AiAssistant.js

@@ -0,0 +1,60 @@
+/**
+ * Vendor-agnostic AI hook. BeeLadybug never ships an API key or a model:
+ * the host app injects complete({ question, snapshot }).
+ */
+
+const SECRET_KEY = /key|token|secret|password|authorization|cookie|apikey/i;
+
+/**
+ * @param {import('./BeeLadybugCore.js').BeeLadybugCore} core
+ * @param {string} question
+ */
+export function buildAssistantSnapshot(core, question) {
+    const logs = core.getLogs().slice(-40).map((packet) => ({
+        type: packet.type,
+        level: packet.level,
+        source: packet.source,
+        message: String(packet.payload?.message ?? packet.payload?.value ?? packet.type),
+        frame: packet.frame
+    }));
+    const history = core.getPrimaryHistory();
+    return {
+        question: String(question || ''),
+        version: core.version,
+        state: core.getState(),
+        hud: scrub(core.getHud()),
+        logs,
+        history: {
+            name: history.name,
+            min: history.min,
+            max: history.max,
+            avg: history.avg,
+            last: history.last,
+            samples: history.values.slice(-24)
+        }
+    };
+}
+
+export function normalizeAssistant(provider) {
+    if (!provider || typeof provider.complete !== 'function') return null;
+    const name = typeof provider.name === 'string' && provider.name
+        ? provider.name
+        : 'custom';
+    return { name, complete: provider.complete.bind(provider) };
+}
+
+function scrub(value, depth = 0) {
+    if (value == null || typeof value !== 'object') {
+        if (typeof value === 'string' && value.length > 400) return `${value.slice(0, 400)}…`;
+        return value;
+    }
+    if (depth > 4) return '[…]';
+    if (Array.isArray(value)) {
+        return value.slice(0, 24).map((item) => scrub(item, depth + 1));
+    }
+    const out = {};
+    for (const key of Object.keys(value)) {
+        out[key] = SECRET_KEY.test(key) ? '[redacted]' : scrub(value[key], depth + 1);
+    }
+    return out;
+}

package/src/core/BeeLadybugCore.js

@@ -7,8 +7,9 @@
  */
 
 import { UIOverlay } from './UIOverlay.js';
+import { buildAssistantSnapshot, normalizeAssistant } from './AiAssistant.js';
 
-export const BEE_LADYBUG_VERSION = '0.1.0';
+export const BEE_LADYBUG_VERSION = '0.3.0';
 
 export const CORE_DEFAULTS = Object.freeze({
     toggleKey: 'F2',
@@ -92,6 +93,9 @@ export class BeeLadybugCore {
         this.#onKeyDown = (event) => this.#handleKey(event);
         this.#onTick = (now) => this.#tick(now);
         this.#started = false;
+        this.#assistants = new Map();
+        this.#activeAssistant = null;
+        this.#askBusy = false;
 
         this.ui = null;
         if (cfg.ui !== false && typeof document !== 'undefined') {
@@ -121,6 +125,11 @@ export class BeeLadybugCore {
     #onKeyDown;
     #onTick;
     #started;
+    /** @type {Map<string, { name: string, complete: Function }>} */
+    #assistants;
+    /** @type {string | null} */
+    #activeAssistant;
+    #askBusy;
 
     /**
      * Public adapter contract. `type` is a channel name; `payload` is raw data.
@@ -153,6 +162,153 @@ export class BeeLadybugCore {
         return () => this.#listeners.delete(handler);
     }
 
+    get hasAssistant() {
+        return Boolean(this.#activeProvider());
+    }
+
+    get assistantBusy() {
+        return this.#askBusy;
+    }
+
+    /** Registered provider names, insertion order. */
+    getAssistants() {
+        return [...this.#assistants.keys()];
+    }
+
+    /**
+     * 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
+     */
+    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: `No assistant named "${key}". bee.registerAssistant({ name, complete }) first.`
+            });
+            return this;
+        }
+        this.#activeAssistant = key;
+        this.sendData('state', { source: 'ai', key: 'ai.assist', value: key });
+        this.sendData('log', { source: 'ai', message: `assistant active (${key})` });
+        return this;
+    }
+
+    /**
+     * 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 active assistant and print the answer.
+     * @param {string} [question]
+     * @returns {Promise<string|null>}
+     */
+    async ask(question = 'Diagnose the current telemetry.') {
+        const assistant = this.#activeProvider();
+        if (!assistant) {
+            this.sendData('warn', {
+                source: 'ai',
+                message: 'No assistant. bee.registerAssistant({ name, complete }) then ASK AI.'
+            });
+            return null;
+        }
+        if (this.#askBusy) {
+            this.sendData('warn', { source: 'ai', message: 'assistant busy' });
+            return null;
+        }
+        const q = String(question || 'Diagnose the current telemetry.');
+        this.#askBusy = true;
+        this.sendData('state', { source: 'ai', key: 'ai.assist', value: 'thinking' });
+        this.sendData('log', { source: 'ai', message: `ask: ${q}` });
+        try {
+            const snapshot = buildAssistantSnapshot(this, q);
+            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: assistant.name });
+            return text;
+        } catch (err) {
+            this.sendData('error', {
+                source: 'ai',
+                message: err instanceof Error ? err.message : String(err)
+            });
+            this.sendData('state', {
+                source: 'ai',
+                key: 'ai.assist',
+                value: assistant?.name ?? 'error'
+            });
+            return null;
+        } finally {
+            this.#askBusy = false;
+        }
+    }
+
+    #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;
         this.#started = true;
@@ -194,6 +350,9 @@ export class BeeLadybugCore {
         this.#history.clear();
         this.#hud.clear();
         this.#latest.clear();
+        this.#assistants.clear();
+        this.#activeAssistant = null;
+        this.#askBusy = false;
         this.ui?.destroy();
         this.ui = null;
         return this;
@@ -219,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;
@@ -276,7 +439,9 @@ export class BeeLadybugCore {
             coreFps: this.coreFps,
             logCount: this.#logs.length,
             hud: this.getHud(),
-            mode: this.#modeLabel()
+            mode: this.#modeLabel(),
+            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;
@@ -169,6 +219,7 @@ const STYLES = `
 .bl-foot {
   display: flex;
   align-items: center;
+  flex-wrap: wrap;
   gap: 6px;
   padding: 8px 10px;
   border-top: 1px solid rgba(255, 59, 78, 0.22);
@@ -188,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;
@@ -205,22 +281,23 @@ export class UIOverlay {
      */
     constructor(core, options = {}) {
         this.core = core;
-        this.#options = options;
+        void options;
         this.#host = null;
         this.#root = null;
         this.#els = null;
         this.#stickBottom = true;
         this.#lastLogId = 0;
         this.#mounted = false;
+        this.#providerSig = '';
     }
 
-    #options;
     #host;
     #root;
     #els;
     #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>
@@ -268,6 +351,8 @@ export class UIOverlay {
                   <button class="bl-btn" data-act="slow" type="button">F3 SLOW</button>
                   <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>
@@ -285,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) => {
@@ -295,6 +381,8 @@ export class UIOverlay {
             if (act === 'slow') this.core.applySlowMo();
             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', () => {
@@ -316,6 +404,7 @@ export class UIOverlay {
         this.#root = null;
         this.#els = null;
         this.#mounted = false;
+        this.#providerSig = '';
         return this;
     }
 
@@ -364,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;
@@ -415,6 +505,28 @@ export class UIOverlay {
         freeze.dataset.hot = state.frozen ? 'true' : 'false';
         slow.dataset.hot = !state.frozen && state.timeScale !== 1 ? 'true' : 'false';
         live.dataset.hot = !state.frozen && state.timeScale === 1 ? 'true' : 'false';
+        const ask = this.#root.querySelector('[data-act="ask"]');
+        if (ask) {
+            ask.dataset.hot = this.core.hasAssistant ? 'true' : 'false';
+            ask.disabled = Boolean(this.core.assistantBusy);
+        }
+    }
+
+    #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) {
@@ -468,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

@@ -0,0 +1,276 @@
+/**
+ * Public TypeScript surface for bee-ladybug.
+ * Runtime is still plain ESM JavaScript in src/*.js.
+ */
+
+export const BEE_LADYBUG_VERSION: string;
+
+export const WELL_KNOWN_TYPES: readonly [
+    'fps',
+    'metric',
+    'coord',
+    'log',
+    'warn',
+    'error',
+    'state',
+    'sys',
+    'clear'
+];
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export type WellKnownType = (typeof WELL_KNOWN_TYPES)[number];
+
+export interface BeePacket {
+    id: number;
+    type: string;
+    payload: Record<string, unknown>;
+    wallTime: number;
+    simTime: number;
+    frame: number;
+    source: string;
+    level: LogLevel | null;
+}
+
+export interface HudEntry {
+    value: unknown;
+    unit?: string;
+    type: string;
+}
+
+export interface MetricHistory {
+    name: string;
+    values: number[];
+    min: number;
+    max: number;
+    avg: number;
+    last: number;
+}
+
+export interface CoreState {
+    version: string;
+    visible: boolean;
+    frozen: boolean;
+    timeScale: number;
+    simTime: number;
+    frameCount: number;
+    coreFps: number;
+    logCount: number;
+    hud: Record<string, HudEntry>;
+    mode: string;
+    assistant: string | null;
+    assistants: string[];
+}
+
+export interface CoreOptions {
+    toggleKey?: string;
+    slowKey?: string;
+    freezeKey?: string;
+    slowScale?: number;
+    maxLogs?: number;
+    historySize?: number;
+    mount?: 'auto' | false | HTMLElement;
+    ui?: boolean;
+    autoAttach?: boolean;
+    autoStart?: boolean;
+    overlay?: Record<string, unknown>;
+}
+
+export const CORE_DEFAULTS: Required<Omit<CoreOptions, 'overlay' | 'mount'>> & {
+    mount: 'auto';
+};
+
+export interface AssistantSnapshot {
+    question: string;
+    version: string;
+    state: CoreState;
+    hud: Record<string, HudEntry>;
+    logs: Array<{
+        type: string;
+        level: LogLevel | null;
+        source: string;
+        message: string;
+        frame: number;
+    }>;
+    history: {
+        name: string;
+        min: number;
+        max: number;
+        avg: number;
+        last: number;
+        samples: number[];
+    };
+}
+
+export interface AssistantProvider {
+    name?: string;
+    complete(input: { question: string; snapshot: AssistantSnapshot }): unknown;
+}
+
+export function formatSimTime(ms: number): string;
+
+export class BeeLadybugCore {
+    readonly version: string;
+    toggleKey: string;
+    slowKey: string;
+    freezeKey: string;
+    slowScale: number;
+    maxLogs: number;
+    historySize: number;
+    visible: boolean;
+    frozen: boolean;
+    timeScale: number;
+    simTime: number;
+    frameCount: number;
+    coreFps: number;
+    ui: UIOverlay | null;
+
+    constructor(options?: CoreOptions);
+    sendData(type: string, payload?: unknown): BeePacket | null;
+    subscribe(handler: (packet: BeePacket) => void): () => void;
+    start(): this;
+    stop(): this;
+    attach(): this;
+    detach(): this;
+    destroy(): this;
+    show(): this;
+    hide(): this;
+    toggle(): this;
+    freeze(): this;
+    unfreeze(): this;
+    toggleFreeze(): this;
+    setTimeScale(scale: number): this;
+    applySlowMo(): this;
+    restoreRealtime(): this;
+    getState(): CoreState;
+    getLogs(): BeePacket[];
+    getHistory(name: string): MetricHistory;
+    getPrimaryHistory(): MetricHistory;
+    getHud(): Record<string, HudEntry>;
+    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(name?: string): this;
+    ask(question?: string): Promise<string | null>;
+}
+
+export class UIOverlay {
+    core: BeeLadybugCore | null;
+    constructor(core: BeeLadybugCore, options?: Record<string, unknown>);
+    mount(target?: 'auto' | HTMLElement): this;
+    unmount(): this;
+    destroy(): this;
+    setVisible(visible: boolean): this;
+    onPacket(packet: BeePacket): void;
+    onClear(channel?: string): void;
+    render(): void;
+}
+
+export interface CanvasEntity {
+    name?: string;
+    label?: string;
+    id?: string | number;
+    role?: string;
+    primary?: boolean;
+    x?: number;
+    y?: number;
+    worldX?: number;
+    worldY?: number;
+    width?: number;
+    height?: number;
+    w?: number;
+    h?: number;
+    active?: boolean;
+    colliding?: boolean;
+    [key: string]: unknown;
+}
+
+export interface CanvasAdapterOptions {
+    canvas?: HTMLCanvasElement | null;
+    entities?: CanvasEntity[];
+    overlay?: boolean;
+    computeCollisions?: boolean;
+    colorActive?: string;
+    colorColliding?: string;
+    colorInactive?: string;
+    source?: string;
+}
+
+export const CANVAS_ADAPTER_DEFAULTS: Required<
+    Omit<CanvasAdapterOptions, 'canvas' | 'entities'>
+>;
+
+export class CanvasAdapter {
+    core: BeeLadybugCore | null;
+    canvas: HTMLCanvasElement | null;
+    entities: CanvasEntity[];
+    overlayEnabled: boolean;
+    computeCollisions: boolean;
+    frozen: boolean;
+    timeScale: number;
+    constructor(core: BeeLadybugCore, options?: CanvasAdapterOptions);
+    attach(): this;
+    detach(): this;
+    setCanvas(canvas: HTMLCanvasElement | null): this;
+    setEntities(entities: CanvasEntity[]): this;
+    pump(ctx?: CanvasRenderingContext2D): this;
+}
+
+export interface WebDOMAdapterOptions {
+    root?: ParentNode | null;
+    overlay?: boolean;
+    autoTick?: boolean;
+    watch?: string[];
+    source?: string;
+    colorHover?: string;
+    colorWatch?: string;
+    colorMargin?: string;
+    colorPadding?: string;
+    colorContent?: string;
+}
+
+export const WEB_DOM_ADAPTER_DEFAULTS: Required<Omit<WebDOMAdapterOptions, 'root'>>;
+
+export class WebDOMAdapter {
+    core: BeeLadybugCore | null;
+    root: ParentNode | null;
+    overlayEnabled: boolean;
+    autoTick: boolean;
+    watch: string[];
+    frozen: boolean;
+    timeScale: number;
+    hover: Element | null;
+    constructor(core: BeeLadybugCore, options?: WebDOMAdapterOptions);
+    attach(): this;
+    detach(): this;
+    setRoot(root: ParentNode | null): this;
+    pump(): this;
+}
+
+export type PythonBridgeStatus = 'idle' | 'connecting' | 'open' | 'closed';
+
+export interface PythonBridgeOptions {
+    url?: string;
+    autoReconnect?: boolean;
+    reconnectMs?: number;
+    source?: string;
+}
+
+export const PYTHON_BRIDGE_DEFAULTS: Required<PythonBridgeOptions>;
+
+export class PythonBridge {
+    core: BeeLadybugCore | null;
+    url: string;
+    autoReconnect: boolean;
+    reconnectMs: number;
+    source: string;
+    status: PythonBridgeStatus;
+    readonly connected: boolean;
+    constructor(core: BeeLadybugCore, options?: PythonBridgeOptions);
+    connect(url?: string): this;
+    disconnect(): this;
+    ingest(raw: unknown): this;
+}

package/src/index.js

@@ -2,3 +2,4 @@ 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 { PythonBridge, PYTHON_BRIDGE_DEFAULTS } from './adapters/python/PythonBridge.js';